Access tokens

Use this API to interact with access tokens including:

List all group access tokens

GET /api/v4/groups/{id}/access_tokens

Lists all group access tokens for a specified group.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessToken
`400`	Bad Request	—
`404`	Not Found	—

Create a group access token

POST /api/v4/groups/{id}/access_tokens

Creates a group access token for a specified group. You cannot create a token with an access level greater than your account. For example, a user with the Maintainer role cannot create a group access token with the Owner role. You must use a personal access token with this endpoint. You cannot authenticate with a group access token.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID Example: `2`

Request body (application/json)

Property	Type	Description
`access_level`	Integer	The access level of the token in the group Allowed values: `10`, `15`, `20`, `25`, `30`, `40`, `50` Default: `40`
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	The expiration date of the token. If ‘Require personal access token expiry’ is enabled, you must provide a valid value, if not, the token will never expire Example: `2026-02-14`
`name` Required	String	The name of the access token Example: `My token`
`scopes` Required	Array of strings	The permissions of the token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Rotate a group access token

POST /api/v4/groups/{id}/access_tokens/self/rotate

Rotates a group access token by passing it to the API in a header.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—
`405`	Method not allowed	—

Retrieve details on a group access token

GET /api/v4/groups/{id}/access_tokens/{token_id}

Retrieves details on a specified group access token.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the group
`token_id` Path, required	String	The ID of the token

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a group access token

DELETE /api/v4/groups/{id}/access_tokens/{token_id}

Revokes a specified group access token.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID
`token_id` Path, required	String	The ID of the token

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not found	—

Rotate a group access token

POST /api/v4/groups/{id}/access_tokens/{token_id}/rotate

Rotates a group access token. This immediately revokes the previous token and creates a token. Generally, this endpoint rotates a specific group access token by authenticating with a personal access token. You can also use a group access token to rotate itself. If you attempt to use this endpoint to rotate a token that was previously revoked, any active tokens from the same token family are revoked. This feature was introduced in GitLab 16.0.

Parameters

Name	Type	Description
`id` Path, required	String	The group ID
`token_id` Path, required	String	The ID of the token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all personal access tokens for a group service account

GET /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens

Lists all personal access tokens for a specified group service account

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the group
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	401 Unauthorized	—
`403`	Forbidden	—
`404`	404 Group Not Found	—

Create a personal access token for a group service account

POST /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens

Creates a personal access token for a specified group service account. Available only for group Owners and administrators. This feature was introduced in GitLab 16.1.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the group
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`name` Required	String	The name of the access token Example: `My token`
`scopes` Required	Array of strings	The array of scopes of the personal access token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a personal access token for a group service account

DELETE /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}

Revokes a specified personal access token for a group service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the group
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Rotate a personal access token for a group service account

POST /api/v4/groups/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}/rotate

Rotates a specified personal access token for a group service account. This revokes the existing token and creates a token with the same name, description, and scopes.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the group
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all personal access tokens

GET /api/v4/personal_access_tokens

Lists all personal access tokens accessible by the authenticated user. For administrators, returns all personal access tokens in the instance. For non-administrators, returns all of their personal access tokens.

Parameters

Name	Type	Description
`user_id` Query	Integer	Filter PATs by User ID Example: `2`
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	Unauthorized	—

Retrieve a personal access token

GET /api/v4/personal_access_tokens/self

Retrieves a specified personal access token by passing it to the API in a header.

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`401`	Unauthorized	—
`404`	Not found	—

Revoke a personal access token

DELETE /api/v4/personal_access_tokens/self

Revokes a personal access token by passing it to the API in a header.

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—

List all token associations

GET /api/v4/personal_access_tokens/self/associations

Lists all groups and projects accessible by the personal access token used to authenticate the request. Generally, this includes any groups or projects that the user is a member of.

Parameters

Name	Type	Description
`min_access_level` Query	Integer	Limit by minimum access level of authenticated user Allowed values: `10`, `15`, `20`, `25`, `30`, `40`, `50`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Rotate a personal access token

POST /api/v4/personal_access_tokens/self/rotate

Rotates a personal access token by passing it to the API in a header

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`405`	Method not allowed	—

Retrieve a personal access token

GET /api/v4/personal_access_tokens/{id}

Retrieves details for a specified personal access token. Administrators can retrieve details on any token. Non-administrators can only retrieve details on their own tokens.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of a personal access token

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	Unauthorized	—
`404`	Not found	—

Revoke a personal access token

DELETE /api/v4/personal_access_tokens/{id}

Revokes a specified personal access token. Administrators can revoke tokens for any user. Non-administrators can only revoke their own tokens.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of a personal access token

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Rotate a personal access token

POST /api/v4/personal_access_tokens/{id}/rotate

Rotates a specified personal access token. This revokes the previous token and creates a token that expires after one week. Administrators can revoke tokens for any user. Non-administrators can only revoke their own tokens.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of a personal access token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all project access tokens

GET /api/v4/projects/{id}/access_tokens

Lists all project access tokens for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessToken
`400`	Bad Request	—
`404`	Not Found	—

Create a project access token

POST /api/v4/projects/{id}/access_tokens

Creates a project access token for a specified project. You cannot create a token with an access level greater than your account. For example, a user with the Maintainer role cannot create a project access token with the Owner role. You must use a personal access token with this endpoint. You cannot authenticate with a project access token.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID Example: `2`

Request body (application/json)

Property	Type	Description
`access_level`	Integer	The access level of the token in the project Allowed values: `10`, `15`, `20`, `25`, `30`, `40`, `50` Default: `40`
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	The expiration date of the token. If ‘Require personal access token expiry’ is enabled, you must provide a valid value, if not, the token will never expire Example: `2026-02-14`
`name` Required	String	The name of the access token Example: `My token`
`scopes` Required	Array of strings	The permissions of the token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Rotate a project access token

POST /api/v4/projects/{id}/access_tokens/self/rotate

Rotates a project access token by passing it to the API in a header.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—
`405`	Method not allowed	—

Retrieve details on a project access token

GET /api/v4/projects/{id}/access_tokens/{token_id}

Retrieves details on a specified project access token.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`token_id` Path, required	String	The ID of the token

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a project access token

DELETE /api/v4/projects/{id}/access_tokens/{token_id}

Revokes a specified project access token.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`token_id` Path, required	String	The ID of the token

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not found	—

Rotate a project access token

POST /api/v4/projects/{id}/access_tokens/{token_id}/rotate

Rotates a project access token. This immediately revokes the previous token and creates a token. Generally, this endpoint rotates a specific project access token by authenticating with a personal access token. You can also use a project access token to rotate itself. If you attempt to use this endpoint to rotate a token that was previously revoked, any active tokens from the same token family are revoked. This feature was introduced in GitLab 16.0.

Parameters

Name	Type	Description
`id` Path, required	String	The project ID
`token_id` Path, required	String	The ID of the token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesResourceAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

List all personal access tokens for a project service account

GET /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens

Lists all personal access tokens for a specified project service account

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`200`	OK	APIEntitiesPersonalAccessToken
`400`	Bad Request	—
`401`	401 Unauthorized	—
`403`	Forbidden	—
`404`	404 Project Not Found	—

Create a personal access token for a project service account

POST /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens

Creates a personal access token for a specified project service account. Available only for project Owners, Maintainers, and administrators.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`name` Required	String	The name of the access token Example: `My token`
`scopes` Required	Array of strings	The array of scopes of the personal access token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke a personal access token for a project service account

DELETE /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}

Revokes a specified personal access token for a project service account.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—

Rotate a personal access token for a project service account

POST /api/v4/projects/{id}/service_accounts/{user_id}/personal_access_tokens/{token_id}/rotate

Rotates a specified personal access token for a project service account. This revokes the existing token and creates a token with the same name, description, and scopes.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`token_id` Path, required	Integer	The ID of the personal access token
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	The expiration date of the token Example: `2021-01-31`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Create a personal access token

POST /api/v4/user/personal_access_tokens

Creates a personal access token for the currently authenticated user. For security purposes, the token is limited to the k8s_proxy and self_rotate scope. Token values are included with the response, but cannot be retrieved later. This feature was introduced in GitLab 16.5.

Request body (application/json)

Property	Type	Description
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`granular_scopes`	Array of objects	List of granular scopes to assign to the token
`granular_scopes[].access` Required	String	Access to configure for the granular scope Allowed values: `personal_projects`, `all_memberships`, `selected_memberships`, `user`, `instance` Minimum length: `1`
`granular_scopes[].group_ids`	Array of integers	IDs of groups to associate with the granular scope, when access is `selected_memberships`
`granular_scopes[].permissions` Required	Array of strings	List of permissions for the granular scope
`granular_scopes[].project_ids`	Array of integers	IDs of projects to associate with the granular scope, when access is `selected_memberships`
`name` Required	String	The name of the access token Example: `My token`
`scopes`	Array of strings	The array of scopes of the personal access token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—

List all impersonation tokens for a user

GET /api/v4/users/{user_id}/impersonation_tokens

Lists all impersonation tokens for a specified user. Administrators only.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the user
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`state` Query	String	Filters (all\|active\|inactive) impersonation_tokens Allowed values: `all`, `active`, `inactive` Default: `all`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesImpersonationToken
`400`	Bad Request	—
`404`	Not Found	—

Create an impersonation token

POST /api/v4/users/{user_id}/impersonation_tokens

Creates an impersonation token. These tokens are used to act on behalf of a user and can perform API calls as well as Git read and write actions. These tokens are not visible to the associated user on their profile settings page. Token values are included with the response, but cannot be retrieved later. Administrators only.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the user

Request body (application/json)

Property	Type	Description
`description`	String	The description of the personal access token
`expires_at`	String (date)	The expiration date in the format YEAR-MONTH-DAY of the impersonation token
`granular_scopes`	Array of objects	List of granular scopes to assign to the token. Mutually exclusive with `scopes`
`granular_scopes[].access` Required	String	Access to configure for the granular scope Allowed values: `personal_projects`, `all_memberships`, `selected_memberships`, `user`, `instance` Minimum length: `1`
`granular_scopes[].group_ids`	Array of integers	IDs of groups to associate with the granular scope, when access is `selected_memberships`
`granular_scopes[].permissions` Required	Array of strings	List of permissions for the granular scope
`granular_scopes[].project_ids`	Array of integers	IDs of projects to associate with the granular scope, when access is `selected_memberships`
`name` Required	String	The name of the impersonation token
`scopes`	Array of strings	The array of scopes of the impersonation token. Mutually exclusive with `granular_scopes`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesImpersonationTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Retrieve an impersonation token for a user

GET /api/v4/users/{user_id}/impersonation_tokens/{impersonation_token_id}

Retrieves an impersonation token for a specified user. Administrators only.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the user
`impersonation_token_id` Path, required	Integer	The ID of the impersonation token

Responses

Code	Description	Schema
`200`	OK	APIEntitiesImpersonationToken
`400`	Bad Request	—
`404`	Not Found	—

Revoke an impersonation token

DELETE /api/v4/users/{user_id}/impersonation_tokens/{impersonation_token_id}

Revokes an impersonation token for a specified user. Administrators only.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the user
`impersonation_token_id` Path, required	Integer	The ID of the impersonation token

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Create a personal access token for a user

POST /api/v4/users/{user_id}/personal_access_tokens

Creates a personal access token for a user. Token values are included with the response, but cannot be retrieved later. Administrators only.

Parameters

Name	Type	Description
`user_id` Path, required	Integer	The ID of the user

Request body (application/json)

Property	Type	Description
`description`	String	The description of the access token Example: `A token used for k8s`
`expires_at`	String (date)	Expiration date of the access token in ISO format (YYYY-MM-DD). If undefined, the date is set to the maximum allowable lifetime limit Example: `2021-01-31`
`name` Required	String	The name of the access token Example: `My token`
`scopes` Required	Array of strings	The array of scopes of the personal access token

Responses

Code	Description	Schema
`201`	Created	APIEntitiesPersonalAccessTokenWithToken
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesImpersonationToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`impersonation`	String	—
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`user_id`	Integer (int64)	Example: `3`

APIEntitiesImpersonationTokenWithToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`impersonation`	String	—
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`token`	String	—
`user_id`	Integer (int64)	Example: `3`

APIEntitiesPersonalAccessToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`user_id`	Integer (int64)	Example: `3`

APIEntitiesPersonalAccessTokenGranularScope

Property	Type	Description
`access`	String	Example: `personal_projects`
`group_id`	Integer (int64)	Example: `5`
`permissions`	Array	Example: `["read_job"]`
`project_id`	Integer (int64)	Example: `3`

APIEntitiesPersonalAccessTokenWithToken

Property	Type	Description
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`token`	String	—
`user_id`	Integer (int64)	Example: `3`

APIEntitiesResourceAccessToken

Property	Type	Description
`access_level`	Integer	Allowed values: `10`, `20`, `30`, `40`, `50` Example: `40`
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`resource_id`	Integer	Example: `1234`
`resource_type`	String	Allowed values: `project`, `group` Example: `project`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`user_id`	Integer (int64)	Example: `3`

APIEntitiesResourceAccessTokenWithToken

Property	Type	Description
`access_level`	Integer	Allowed values: `10`, `20`, `30`, `40`, `50` Example: `40`
`active`	Boolean	—
`created_at`	String (date-time)	—
`description`	String	Example: `Token to manage api`
`expires_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`granular`	Boolean	—
`granular_scopes`	Array of APIEntitiesPersonalAccessTokenGranularScope	—
`id`	Integer (int64)	Example: `2`
`last_used_at`	String (date-time)	Example: `2020-08-31T15:53:00.073Z`
`last_used_ips`	Array of strings	The five most recent unique IP addresses that have authenticated with this token. When the limit is reached, the oldest IP address is removed. The list updates once per minute per token Example: `["127.0.0.1","127.0.0.2","127.0.0.3"]`
`name`	String	Example: `John Doe`
`resource_id`	Integer	Example: `1234`
`resource_type`	String	Allowed values: `project`, `group` Example: `project`
`revoked`	Boolean	—
`scopes`	Array	Example: `["api"]`
`token`	String	—
`user_id`	Integer (int64)	Example: `3`

List all group access tokens

Create a group access token

Rotate a group access token

Retrieve details on a group access token

Revoke a group access token

Rotate a group access token

List all personal access tokens for a group service account

Create a personal access token for a group service account

Revoke a personal access token for a group service account

Rotate a personal access token for a group service account

List all personal access tokens

Retrieve a personal access token

Revoke a personal access token

List all token associations

Rotate a personal access token

Retrieve a personal access token

Revoke a personal access token

Rotate a personal access token

List all project access tokens

Create a project access token

Rotate a project access token

Retrieve details on a project access token

Revoke a project access token

Rotate a project access token

List all personal access tokens for a project service account

Create a personal access token for a project service account

Revoke a personal access token for a project service account

Rotate a personal access token for a project service account

Create a personal access token

List all impersonation tokens for a user

Create an impersonation token

Retrieve an impersonation token for a user

Revoke an impersonation token

Create a personal access token for a user

Schemas

APIEntitiesImpersonationToken

APIEntitiesImpersonationTokenWithToken

APIEntitiesPersonalAccessToken

APIEntitiesPersonalAccessTokenGranularScope

APIEntitiesPersonalAccessTokenWithToken

APIEntitiesResourceAccessToken

APIEntitiesResourceAccessTokenWithToken

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error