• Create a personal access token
• Create a personal access token with limited scopes for your account
• Get all impersonation tokens of a user
• Get an impersonation token of a user
• Create an impersonation token
• Revoke an impersonation token

User tokens API

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

Create a personal access token

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:

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:

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:

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:

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:

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:

Example request:

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