Token Revocation API

The Token Revocation API is an externally-deployed HTTP API that interfaces with GitLab to receive and revoke API tokens and other secrets detected by GitLab Secret Detection. See the high-level architecture to understand the Secret Detection post-processing and revocation flow.

GitLab.com uses the internally-maintained Secret Revocation Service (team-members only) as its Token Revocation API. For GitLab self-managed, you can create your own API and configure GitLab to use it.

Implement a Token Revocation API for self-managed

GitLab self-managed instances interested in using the revocation capabilities must:

  • Implement and deploy your own Token Revocation API.
  • Configure the GitLab instance to use the Token Revocation API.

Your service must:

  • Match the API specification below.
  • Provide two endpoints:
    • Fetching revocable token types.
    • Revoking leaked tokens.
  • Be rate-limited and idempotent.

Requests to the documented endpoints are authenticated using API tokens passed in the Authorization header. Request and response bodies, if present, are expected to have the content type application/json.

All endpoints may return these responses:

  • 401 Unauthorized
  • 405 Method Not Allowed
  • 500 Internal Server Error

GET /v1/revocable_token_types

Returns the valid type values for use in the revoke_tokens endpoint.

note
These values match the concatenation of the secrets analyzer’s primary identifier by means of concatenating the primary_identifier.type and primary_identifier.value. For example, the value gitleaks_rule_id_gitlab_personal_access_token matches the following finding identifier:
{"type": "gitleaks_rule_id", "name": "Gitleaks rule ID GitLab Personal Access Token", "value": "GitLab Personal Access Token"}
Status Code Description
200 The response body contains the valid token type values.

Example response body: 

{
    "types": ["gitleaks_rule_id_gitlab_personal_access_token"]
}

POST /v1/revoke_tokens

Accepts a list of tokens to be revoked by the appropriate provider. Your service is responsible for communicating with each provider to revoke the token.

Status Code Description
204 All submitted tokens have been accepted for eventual revocation.
400 The request body is invalid or one of the submitted token types is not supported. The request should not be retried.
429 The provider has received too many requests. The request should be retried later.

Example request body (space characters added to token value to prevent secret detection warnings): 

[{
    "type": "gitleaks_rule_id_gitlab_personal_access_token",
    "token": "glpat - 8GMtG8Mf4EnMJzmAWDU",
    "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile1.java"
},
{
    "type": "gitleaks_rule_id_gitlab_personal_access_token",
    "token": "glpat - tG84EGK33nMLLDE70zU",
    "location": "https://example.com/some-repo/blob/abcdefghijklmnop/compromisedfile2.java"
}]

Configure GitLab to interface with the Token Revocation API

You must configure the following database settings in the GitLab instance:

Setting Type Description
secret_detection_token_revocation_enabled Boolean Whether automatic token revocation is enabled
secret_detection_token_revocation_url String A fully-qualified URL to the /v1/revoke_tokens endpoint of the Token Revocation API
secret_detection_revocation_token_types_url String A fully-qualified URL to the /v1/revocable_token_types endpoint of the Token Revocation API
secret_detection_token_revocation_token String A pre-shared token to authenticate requests to the Token Revocation API

For example, to configure these values in the Rails console: 

::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_token: 'MYSECRETTOKEN')
::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_url: 'https://gitlab.example.com/revocation_service/v1/revoke_tokens')
::Gitlab::CurrentSettings.update!(secret_detection_revocation_token_types_url: 'https://gitlab.example.com/revocation_service/v1/revocable_token_types')
::Gitlab::CurrentSettings.update!(secret_detection_token_revocation_enabled: true)

After you configure these values, the Token Revocation API will be called according to the high-level architecture diagram.