---
title: Query, validate, and cancel tokens
description: Query, validate, and cancel tokens issued by PingAM Security Token Service instances using REST API calls with token persistence enabled
component: pingam
version: 7.5
page_id: pingam:sts:sts-query-validate-cancel
canonical_url: https://docs.pingidentity.com/pingam/8.1/sts/sts-query-validate-cancel.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Security Token Service (STS)", "Rest", "SAML 2.0", "OpenID Connect (OIDC)", "JSON"]
page_aliases: ["sts-guide:sts-query-validate-cancel.adoc"]
superseded_by: https://docs.pingidentity.com/pingam/8.1/sts/sts-query-validate-cancel.html
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 a REST STS instance
  query-validate-cancel-soap-sts-instance: Validate and cancel tokens by invoking a SOAP STS instance
---

# Query, validate, and cancel tokens

Both REST and SOAP STS instances support *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 both REST and SOAP STS instances' configuration under Realms > *realm name* > STS > *STS instance name* > 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 OpenID Connect 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 *for both REST and SOAP STS instances* using REST API calls.

When using the `sts-tokengen` endpoint, be sure to 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 OpenID Connect tokens for the `demo` user for the `username-transformer` STS instance:

```bash
$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/sts_id+eq+\'username-transformer\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "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 the `demo` user. The results show that AM has issued two OpenID Connect tokens:

```bash
$ curl \
--request GET \
--header "iPlanetDirectoryPro: AQIC5..." \
https://openam.example.com:8443/openam/sts-tokengen?_queryFilter=\/token_principal+eq+\'demo\'
{
    "result":[
        {
            "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "_rev":"",
            "token_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "token_type":"OPENIDCONNECT",
            "expiration_time":1459376096
        },
        {
            "_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "_rev":"",
            "token_id":"7CB70009970D1AAFF177AC2A08D58405EDC35DF5",
            "sts_id":"username-transformer",
            "principal_name":"demo",
            "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://openam.example.com:8443/openam/sts-tokengen/B663D248CE4C3B63A7422000B03B8F5E0F8E443B
{
    "_id":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "_rev":"B663D248CE4C3B63A7422000B03B8F5E0F8E443B",
    "result":"token with id B663D248CE4C3B63A7422000B03B8F5E0F8E443B successfully removed."
}
```

## Validate and cancel tokens by invoking a REST STS instance

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

To validate a token, use the `validate` action. The following example validates an OpenID Connect token previously issued by the `username-transformer` REST 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://openam.example.com:8443/openam/rest-sts/username-transformer?_action=validate
{
    "token_valid":true
}
```

To cancel a token, use the `cancel` action. The following example cancels an OpenID Connect token previously issued by the `username-transformer` REST 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://openam.example.com:8443/openam/rest-sts/username-transformer?_action=cancel
{
    "result":"OPENIDCONNECT token cancelled successfully."
}
```

## Validate and cancel tokens by invoking a SOAP STS instance

The source code for the `validateToken` and `cancelToken` methods in the `org.forgerock.openam.sts.soap.SoapSTSConsumer` class provides information needed to construct WS-Trust 1.4-compliant calls for validating and cancelling tokens.

Locate the `org.forgerock.openam.sts.soap.SoapSTSConsumer` class under `openam-sts/openam-soap-sts/openam-soap-sts-client` in the AM source code.