The token revocation endpoint is defined in the OAuth 2.0 Token Revocation specification (tools.ietf.org/html/rfc7009). It allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. The revocation request invalidates the actual token and possibly other tokens based on the same authorization grant.

Note:

Per specification, this endpoint accepts only the HTTP POST method.

Endpoint: /as/revoke_token.oauth2

Important:

Direct access token revocation is only supported for Internally Managed Reference Tokens. Access tokens of the type JSON Web Token (JWT) do not support direct revocation. JWT access tokens can only be indirectly revoked if the associated refresh token is revoked, and the JWT's configuration field Access Grant GUID Claim Name is set for the given access token manager instance.

If a refresh token is revoked, the associated access grant and access tokens will be revoked as well. If an access token is revoked, the associated access grant and refresh token remain untouched with the exception of the implicit grant type. If the Reuse Existing Persistent Access Grants for GrantTypes check box is selected in the OAuth Server > Authorization Server Settings screen, the implicit access grant will also be revoked with the access token.

The following table describes parameters for this endpoint. The required Content-Type value is application/x-www-form-urlencoded when transmitting via the HTTP POST method.

Parameter Description
token

(Required)

The token that the client wants to revoke.
Important:

This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body, instead of in a query string.

token_type_hint A hint about the type of token submitted for revocation. PingFederate supports the following values:
  • access_token
  • refresh_token

The following table describes parameters for this endpoint. The required Content-Type value is application/x-www-form-urlencoded.

OAuth client identification and authentication

The authentication requirement of this endpoint depends on the client authentication method configured for the clients.

Authentication method Parameters
Client secret Clients can present their client identifier and client secret using the HTTP Basic authentication scheme, where the client identifier is the username, and the client secret is the password.

Alternatively, clients can provide credentials using these request parameters: client_id and client_secret.

Important:

This is a sensitive parameter. To avoid recording it in web server logs, we recommend to only pass in this parameter (via the HTTP POST method) in the message body or through the use of the HTTP Basic authentication scheme, instead of in a query string.

Client certificate Clients must present their client certificate for mutual TLS authentication. The issuer and the subject DN of the client certificate must match values configured for the clients.
Private key JWT Clients must include request parameters client_assertion_type and client_assertion in the message body of their requests.
client_assertion_type
The value describes the format of the assertion as defined by the authorization server. For the private_key_jwt client authentication method, the value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
client_assertion
The value is the authentication token.

Example:

...
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%
3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=
eyJhbGciOiJSUzI1NiIs...LbSWi1YO-TILOd4L7ZCg&
...
Note:

For readability, line breaks are inserted and the authentication token is truncated.

For more information about the private_key_jwt client authentication method, see Client Authentication in the OpenID Connect specification (openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) and Using Assertions for Client Authentication in RFC7521 (tools.ietf.org/html/rfc7521#section-4.2).

None Clients must pass in the client_id parameter in a query string or the message body to identify themselves.