Token Revocation Endpoint

The HID Authentication Service server exposes a token revocation endpoint, conforming to the OAuth 2.0 Token revocation specification.

The revoke endpoint supports public clients.

Copy

The endpoint is exposed at the following URL (and can be obtained from the server discovery endpoint):

https://[base-server-url]/{tenant}/authn/revoke [POST]
Method Details
POST

Token Revocation Request

To request a token, confidential clients must authenticate to the server with their client_id and client_secret credentials obtained at registration.

Note: While basic is the default authentication method, for security reasons, it is recommended to configure a stronger authentication method, such as client secret POST, private key JWT or the HID custom authentication method client_secret_pki.
Copy

Sample token revocation request with basic authorization (for an access token)

POST https://[base-server-url]/{tenant}/authn/revoke
HTTP/1.1 
Content-Type: application/x-www-form-urlencoded
Authorization: Basic c3BsLWFwaTphY3RpdmNhcmQ=
token=RTp7HwAAAX0TWZYAgyHTl0UEiGlpfoxJjAlcwvR7&token_type_hint=access_token
Copy

Sample token revocation request with bearer authorization (for an access token)

POST https://[base-server-url]/{tenant}/authn/revoke
HTTP/1.1 
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer RTp7HwAAAX0TWZYAgyHTl0UEiGlpfoxJjAlcwvR7
token=RTp7HwAAAX0TW9ioFKvN89MtEVI9DDfwr9z9DxRQ&token_type_hint=access_token&client_id=spl-pai

Where:

  • token - populated with the token to revoke (mandatory)
  • token_type_hint - specifies the type of the token (for example, refresh_token or access_token) (optional)

    If this field is incorrectly populated, the server extends the search to other types of token (see RFC7009 specification - section 2.1).

  • client_id - ID of the OpenID client from the bearer (mandatory for bearer authorization, not required for basic authorization)

Token Revocation Response

The server responds with an HTTP 200 status regardless of whether the submitted token is valid or not (as required by the RFC7009 specification - section 2.2):

Copy 
HTTP/1.1 200 OK
Note: When an access token is revoked, the corresponding refresh token is also revoked.

Error/Failure Responses

Code Label Possible Errors
400 BAD REQUEST invalid_request
401 UNAUTHORIZED invalid_client
403 FORBIDDEN access_denied
500 INTERNAL SERVER ERROR server_error
Copy

Sample error response

HTTP/1.1 400 Bad Request
{"error_description":"Invalid request: Invalid token","error":"invalid_request"}