Token information API

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
Status: Experiment

Use this API to retrieve details about arbitrary tokens and to revoke them. Unlike other APIs that expose token information, this API allows you to retrieve details or revoke tokens without knowing the specific type of token.

Token prefixes

When making a request, personal, project or group access tokens must begin with glpat or the current custom prefix. If the token begins with a previous custom prefix, the operation will fail. Interest in support for previous custom prefixes is tracked in issue 165663.

Prerequisites:

  • You must have administrator access to the instance.

Get information on a token

History

Gets information for a given token. This endpoint supports the following tokens:

POST /api/v4/admin/token

Supported attributes:

Attribute Type Required Description
token string Yes Existing token to identify. Personal, project or group access tokens must begin with glpat or the current custom prefix.

If successful, returns 200 and information about the token.

Can return the following status codes:

  • 200 OK: Information about the token.
  • 401 Unauthorized: The user is not authorized.
  • 403 Forbidden: The user is not an administrator.
  • 404 Not Found: The token was not found.
  • 422 Unprocessable: The token type is not supported.

Example request:

curl --request POST \
  --url "https://gitlab.example.com/api/v4/admin/token" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"token": "glpat-<example-token>"}'

Example response:

{
 "id": 1,
 "user_id": 70,
 "name": "project-access-token",
 "revoked": false,
 "expires_at": "2024-10-04",
 "created_at": "2024-09-04T07:19:18.652Z",
 "updated_at": "2024-09-04T07:19:18.652Z",
 "scopes": [
  "api",
  "read_api"
 ],
 "impersonation": false,
 "expire_notification_delivered": false,
 "last_used_at": null,
 "after_expiry_notification_delivered": false,
 "previous_personal_access_token_id": null,
 "advanced_scopes": null,
 "organization_id": 1
}

Revoke a token

History
The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Revokes or resets a given token based on the token type. This endpoint supports the following token types:

Token type Supported action
Personal access tokens Revoke
Project access tokens Revoke
Group access tokens Revoke
Deploy tokens Revoke
Cluster agent tokens Revoke
Feed tokens Reset
Runner authentication tokens Reset
OAuth application secrets Reset
DELETE /api/v4/admin/token

Supported attributes:

Attribute Type Required Description
token string Yes Existing token to revoke. Personal, project or group access tokens must begin with glpat or the current custom prefix.

If successful, returns 204 without content.

Can return the following status codes:

  • 204 No content: Token has been revoked.
  • 401 Unauthorized: The user is not authorized.
  • 403 Forbidden: The user is not an administrator.
  • 404 Not Found: The token was not found.
  • 422 Unprocessable: The token type is not supported.

Example request:

curl --request DELETE \
  --url "https://gitlab.example.com/api/v4/admin/token" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header 'Content-Type: application/json' \
  --data '{"token": "glpat-<example-token>"}'