Skip to content

User tokens API

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

You can manage personal access tokens and impersonation tokens by using the REST API.

Create a personal access token

  • The expires_at attribute default was introduced in GitLab 16.0.

Create a new personal access token. Token values are returned once so, make sure you save it because you can't access it again.

Prerequisites:

  • You must be an administrator.
POST /users/:user_id/personal_access_tokens

Supported attributes:

Attribute Type Required Description
user_id integer yes ID of the user.
name string yes Name of the personal access token.
expires_at date no Expiration date of the access token in ISO format (YYYY-MM-DD). If no date is set, the expiration is set to the maximum allowable lifetime of an access token.
scopes array yes Array of scopes of the personal access token. See personal access token scopes for possible values.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens"

Example response:

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "scopes": [
        "api"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-12-31",
    "token": "<your_new_access_token>"
}

Create a personal access token with limited scopes for your account

Create a new personal access token for your account.

Prerequisites:

  • You must be authenticated.

For security purposes, the token:

  • Is limited to the k8s_proxy scope. This scope grants permission to perform Kubernetes API calls using the agent for Kubernetes.
  • By default, expires at the end of the day it was created on.

Token values are returned once, so make sure you save the token because you cannot access it again.

POST /user/personal_access_tokens

Supported attributes:

Attribute Type Required Description
name string yes Name of the personal access token.
scopes array yes Array of scopes of the personal access token. Possible values are k8s_proxy.
expires_at array no Expiration date of the access token in ISO format (YYYY-MM-DD). If no date is set, the expiration is at the end of the current day. The expiration is subject to the maximum allowable lifetime of an access token.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "scopes[]=k8s_proxy" "https://gitlab.example.com/api/v4/user/personal_access_tokens"

Example response:

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "scopes": [
        "k8s_proxy"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-10-15",
    "token": "<your_new_access_token>"
}

Get all impersonation tokens of a user

Retrieve every impersonation token of a user. Use the pagination parameters page and per_page to restrict the list of impersonation tokens.

Prerequisites:

  • You must be an administrator.
GET /users/:user_id/impersonation_tokens

Supported attributes:

Attribute Type Required Description
user_id integer yes ID of the user.
state string no Filter tokens based on state: all, active, or inactive.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

Example response:

[
   {
      "active" : true,
      "user_id" : 2,
      "scopes" : [
         "api"
      ],
      "revoked" : false,
      "name" : "mytoken",
      "id" : 2,
      "created_at" : "2017-03-17T17:18:09.283Z",
      "impersonation" : true,
      "expires_at" : "2017-04-04",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   },
   {
      "active" : false,
      "user_id" : 2,
      "scopes" : [
         "read_user"
      ],
      "revoked" : true,
      "name" : "mytoken2",
      "created_at" : "2017-03-17T17:19:28.697Z",
      "id" : 3,
      "impersonation" : true,
      "expires_at" : "2017-04-14",
      "last_used_at": "2017-03-24T09:44:21.722Z"
   }
]

Get an impersonation token of a user

Get a user's impersonation token.

Prerequisites:

  • You must be an administrator.
GET /users/:user_id/impersonation_tokens/:impersonation_token_id

Supported attributes:

Attribute Type Required Description
user_id integer yes ID of the user.
impersonation_token_id integer yes ID of the impersonation token.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2"

Example response:

{
   "active" : true,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "revoked" : false,
   "name" : "mytoken",
   "id" : 2,
   "created_at" : "2017-03-17T17:18:09.283Z",
   "impersonation" : true,
   "expires_at" : "2017-04-04"
}

Create an impersonation token

Create a new impersonation token. You can only create impersonation tokens to impersonate the user and perform both API calls and Git reads and writes. The user can't see these tokens in their profile settings page.

Token values are returned once. Make sure you save it because you can't access it again.

Prerequisites:

  • You must be an administrator.
POST /users/:user_id/impersonation_tokens

Supported attributes:

Attribute Type Required Description
user_id integer yes ID of the user.
name string yes Name of the impersonation token.
expires_at date yes Expiration date of the impersonation token in ISO format (YYYY-MM-DD).
scopes array yes Array of scopes of the impersonation token (api, read_user).

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

Example response:

{
   "id" : 2,
   "revoked" : false,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "token" : "<impersonation_token>",
   "active" : true,
   "impersonation" : true,
   "name" : "mytoken",
   "created_at" : "2017-03-17T17:18:09.283Z",
   "expires_at" : "2017-04-04"
}

Revoke an impersonation token

Revoke an impersonation token.

Prerequisites:

  • You must be an administrator.
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id

Supported attributes:

Attribute Type Required Description
user_id integer yes ID of the user.
impersonation_token_id integer yes ID of the impersonation token.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"