Token information API
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
-
Introduced in GitLab 17.5 with a flag named
admin_agnostic_token_finder
. Disabled by default. -
Generally available in GitLab 17.8. Feature flag
admin_agnostic_token_finder
removed. - Feed tokens added in GitLab 17.6.
- OAuth application secrets added in GitLab 17.7.
- Cluster agent tokens added in GitLab 17.7.
- Runner authentication tokens added in GitLab 17.7.
- Pipeline trigger tokens added in GitLab 17.7.
- CI/CD Job Tokens added in GitLab 17.9.
- Feature flags client tokens added in GitLab 17.9.
- GitLab session cookies added in GitLab 17.9.
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
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
-
Introduced in GitLab 17.7 with a flag named
api_admin_token_revoke
. Disabled by default. - Cluster agent tokens added in GitLab 17.9.
- Runner authentication tokens added in GitLab 17.9.
- OAuth application secrets added in GitLab 17.9.
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>"}'