---
title: Query, validate, and cancel tokens
description: The Security Token Service (STS) instance supports token persistence, which is the ability to store tokens issued for the STS instance in the Core Token Service (CTS). You enable token persistence for STS instances under Realms > realm name > STS > STS instance > General Configuration > Persist Issued Tokens in Core Token Store. Tokens are saved in the CTS for the duration of the token lifetime, which is a configuration property for STS-issued SAML 2.0 and OIDC tokens. Tokens with expired durations are periodically removed from the CTS.
component: pingam
version: 8.1
page_id: pingam:sts:sts-query-validate-cancel
canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-query-validate-cancel.html
keywords: ["Security Token Service (STS)", "Rest", "SAML 2.0", "OpenID Connect (OIDC)", "JSON"]
page_aliases: ["sts-guide:sts-query-validate-cancel.adoc"]
section_ids:
  sts-query-validate-cancel-sts-tokengen: Invoke the sts-tokengen endpoint
  sts-query-validate-cancel-sts-tokengen-query: Query tokens
  sts-query-validate-cancel-sts-tokengen-cancel: Cancel tokens
  query-validate-cancel-rest-sts-instance: Validate and cancel tokens by invoking an STS instance
---

# Query, validate, and cancel tokens

The Security Token Service (STS) instance supports *token persistence*, which is the ability to store tokens issued for the STS instance in the Core Token Service (CTS). You enable token persistence for STS instances under Realms > *realm name* > STS > *STS instance* > General Configuration > Persist Issued Tokens in Core Token Store. Tokens are saved in the CTS for the duration of the token lifetime, which is a configuration property for STS-issued SAML 2.0 and OIDC tokens. Tokens with expired durations are periodically removed from the CTS.

With token persistence enabled for an STS instance, AM provides the ability to query, validate, and cancel tokens issued for the instance:

* *Querying tokens* means listing tokens issued for an STS instance or for a user.

* *Validating a token* means verifying that the token is still present in the CTS.

* *Cancelling a token* means removing the token from the CTS.

## Invoke the sts-tokengen endpoint

The `sts-tokengen` endpoint provides administrators with the ability to query and cancel tokens issued using REST API calls.

When using the `sts-tokengen` endpoint, make sure you provide the token ID for an AM administrator, such as `amAdmin`, as the value of a header whose name is the name of the SSO token cookie, by default `iPlanetDirectoryPro`.

### Query tokens

List tokens issued for an STS instance by using the `queryFilter` action in an HTTP GET call to the `sts-tokengen` endpoint with the `/sts-id` argument.

The following example lists all the tokens issued for the `username-transformer` STS instance. The results show that AM has issued two OIDC tokens for `bjensen` for the `username-transformer` STS instance:

```bash
$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen?_queryFilter=\/sts_id+eq+\'username-transformer\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}
```

List tokens issued for a particular user with the `queryFilter` action in an HTTP GET call to the `sts-tokengen` endpoint with the `/token-principal` argument.

The following example lists all the tokens issued for `bjensen`. The results show that AM has issued two OIDC tokens:

```bash
$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen?_queryFilter=\/token_principal+eq+\'bjensen\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"bjensen",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376098
        }
    ],
    "resultCount":2,
    "pagedResultsCookie":null,
    "totalPagedResultsPolicy":"NONE",
    "totalPagedResults":-1,
    "remainingPagedResults":-1
}
```

### Cancel tokens

Cancel tokens by making an HTTP DELETE call to the `sts-tokengen`/*token-id* endpoint:

```bash
$ curl \
--request DELETE \
--header "iPlanetDirectoryPro: AQIC5…​" \
https://am.example.com:8443/am/sts-tokengen/B663D248CE4C3B63A7422000B03B8F5E0F8E443B
{
    "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "_rev":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "result":"token with id B663D248CE4C3B63A7422000B03B8F5E0F8E443B successfully removed."
}
```

## Validate and cancel tokens by invoking an STS instance

STS users can validate and cancel tokens by making an HTTP POST call to an STS instance's endpoint.

To validate a token, use the `validate` action. The following example validates an OIDC token previously issued by the `username-transformer` STS instance:

```bash
$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Content-Type: application/json" \
--data '{
    "validated_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC…​"
    }
}' \
https://am.example.com:8443/am/rest-sts/username-transformer?_action=validate
{
    "token_valid":true
}
```

To cancel a token, use the `cancel` action. The following example cancels an OIDC token previously issued by the `username-transformer` STS instance:

```bash
$ curl \
--request POST \
--header "iPlanetDirectoryPro: AQIC5…​" \
--header "Content-Type: application/json" \
--data '{
    "cancelled_token_state": {
        "token_type": "OPENIDCONNECT",
        "oidc_id_token": "eyAidHlwIjogIkpXVCIsIC…​"
    }
}' \
 https://am.example.com:8443/am/rest-sts/username-transformer?_action=cancel
{
    "result":"OPENIDCONNECT token cancelled successfully."
}
```