Token information API

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

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

• Personal access tokens
• Impersonation tokens
• Deploy tokens
• Feed tokens
• OAuth application secrets
• Cluster agent tokens
• Runner authentication tokens
• Pipeline trigger tokens
• CI/CD Job Tokens
• Feature flags client tokens
• GitLab session cookies
• Incoming email tokens

POST /api/v4/admin/token

Supported attributes:

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

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

DELETE /api/v4/admin/token

Supported attributes:

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>"}'