Token revocation

1. Client-initiated revocation of tokens

A client can notify the Connect2id server that a previously obtained refresh token, access token or device secret is no longer needed. The credential will be invalidated, plus related credentials, as explained below. This is done by a call to the token revocation endpoint, as specified in RFC 7009.

2. The token revocation endpoint URL

It is advertised in the revocation_endpoint server metadata and has this form:

[issuer-url]/token/revoke

3. Client authentication

Confidential clients must authenticate and public clients must identify themselves as they would at the token endpoint.

4. Web API overview

Resources
/token/revoke [POST]
Representations	Errors
	400 Bad Request 401 Unauthorized 500 Internal Server Error

4. Resources

4.1 /token/revoke

4.1.1 POST

Revokes a credential obtained by the client:

Refresh or access token. Any other tokens issued to the client for the same subject (end-user) will be revoked. If a matching persisted authorisation record exists, it will be deleted.
Device secret for OpenID Connect native SSO. The Connect2id server will end the linked device session. Refresh tokens issued to all clients bound to the device session will no longer be usable. Their access tokens will not be affected.

Header parameters:

[ Authorization ] Used for HTTP basic authentication of the client.
Content-Type Must be set to application/x-www-form-urlencoded.
[ Issuer ] The issuer URL when issuer aliases are configured, or the issuer URL for a tenant (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Tenant-ID header.
[ Tenant-ID ] The tenant ID (in the multi-tenant Connect2id server edition). The tenant can be alternatively specified by the Issuer header.

Body with form parameters:

token The token.
[ token_type_hint ] Optional hint about the type of the submitted token; if omitted the server will use heuristics to determine the token type:
- access_token – the token is an access token
- refresh_token – the token is a refresh token
- device_secret – the token is a device secret

Success:

Code: 200

Errors:

400 Bad Request
401 Unauthorised
500 Internal Server Error

Example token revocation request hinting its type:

POST /token/revoke HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=Ohw8choo.wii3ohCh.Eesh1AeDGong3eir
&token_type_hint=refresh_token

Example token revocation request; the server will be let to determine the token type:

POST /token/revoke HTTP/1.1
Host: c2id.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW

token=Ohw8choo.wii3ohCh.Eesh1AeDGong3eir

The server will return a 200 status regardless of whether the submitted token was valid or not (required by the specification):

HTTP/1.1 200 OK

5. Errors

400 Bad Request

Invalid or malformed request.

Example:

HTTP/1.1 400 Bad Request

401 Unauthorized

The request was denied due to an invalid or missing client authentication. The error_description is a checklist of all possible causes why the client authentication may have failed. The client_auth_id can be used to identify the exact cause.

Example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Invalid client: Possible causes may be missing /
                         invalid client_id, missing client authentication,
                         invalid or expired client secret, invalid or expired
                         JWT authentication, invalid or expired client X.509
                         certificate, or an unexpected client authentication
                         method",
  "client_auth_id"    : "cgXB4EyYViWPt6g2"
}

500 Internal Server Error

An internal server error has occurred. Check the Connect2id server logs for details.

Example:

HTTP/1.1 500 Internal Server Error