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	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the group 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	Description of the access token. Limited to 255 characters Example: `A token used for k8s`
`expires_at`	String (date)	Date when the access token expires. If omitted, the token does not expire, which is accepted only when token expiry is not enforced Example: `2026-02-14`
`name` Required	String	Name of the access token Example: `My token`
`scopes` Required	Array of strings	List of scopes available to 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	ID or URL-encoded path of the group

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	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	ID or URL-encoded path of the group
`token_id` Path, required	String	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	ID or URL-encoded path of the group
`token_id` Path, required	String	ID of the token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	ID or URL-encoded path of the group
`revoked` Query	Boolean	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`user_id` Path, required	Integer	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	ID or URL-encoded path of the group
`user_id` Path, required	Integer	ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	Description of the access token. Limited to 255 characters 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	Name of the access token Example: `My token`
`scopes` Required	Array of strings	Array of approved scopes. For a list of possible values, see access token scopes

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	ID or URL-encoded path of the group
`token_id` Path, required	Integer	ID of the personal access token
`user_id` Path, required	Integer	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	ID or URL-encoded path of the group
`token_id` Path, required	Integer	ID of the personal access token
`user_id` Path, required	Integer	ID of the service account

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. Introduced in GitLab 17.9. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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 personal access tokens by user ID. Non-administrators can only filter their own tokens Example: `2`
`revoked` Query	Boolean	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of 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	Return groups and projects where the current user has at least the specified access level. For a list of values, see roles Allowed values: `10`, `15`, `20`, `25`, `30`, `40`, `50`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list 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)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	ID of the 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	ID of the 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	ID of the personal access token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project 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	Description of the access token. Limited to 255 characters Example: `A token used for k8s`
`expires_at`	String (date)	Date when the access token expires. If omitted, the token does not expire, which is accepted only when token expiry is not enforced Example: `2026-02-14`
`name` Required	String	Name of the access token Example: `My token`
`scopes` Required	Array of strings	List of scopes available to 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	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	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	ID or URL-encoded path of the project
`token_id` Path, required	String	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	ID or URL-encoded path of the project
`token_id` Path, required	String	ID of the token

Request body (application/json)

Property	Type	Description
`expires_at`	String (date)	Date when the access token expires. If omitted, the new token expires one week after rotation when token expiry is enforced, and does not expire otherwise 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	If `true`, only returns revoked tokens. If `false`, only returns tokens that are not revoked Example: `false`
`state` Query	String	Return tokens with the specified state Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Return tokens created on or before the specified time Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Return tokens created on or after the specified time Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Return tokens last used on or before the specified time Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Return tokens last used on or after the specified time Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Return tokens that expire before the specified date Example: `2022-01-01`
`expires_after` Query	String (date)	Return tokens that expire on or after the specified date Example: `2021-01-01`
`search` Query	String	Return tokens that include the specified value in their name Example: `token`
`sort` Query	String	Sort results by the specified field and direction. Possible values are `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, and `name_desc` Example: `created_desc`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list 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	Description of the access token. Limited to 255 characters 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	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	Description of the access token. Limited to 255 characters 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. Exactly one of `scopes`, `granular_scopes` must be provided
`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	Name of the access token Example: `My token`
`scopes`	Array of strings	Array of approved scopes. For a list of possible values, see access token scopes. Exactly one of `scopes`, `granular_scopes` must be provided

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	ID of the user
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`state` Query	String	Filter tokens by state Allowed values: `all`, `active`, `inactive` Default: `all`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID of the user

Request body (application/json)

Property	Type	Description
`description`	String	Description of the impersonation token. Limited to 255 characters
`expires_at`	String (date)	Date when the impersonation token expires. If omitted, the token does not expire, which is accepted only when token expiry is not enforced
`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	Name of the impersonation token
`scopes`	Array of strings	Array of approved scopes. For a list of possible values, see access token scopes. 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	ID of the user
`impersonation_token_id` Path, required	Integer	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	ID of the user
`impersonation_token_id` Path, required	Integer	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	ID of the user

Request body (application/json)

Property	Type	Description
`description`	String	Description of the access token. Limited to 255 characters 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	Name of the access token Example: `My token`
`scopes` Required	Array of strings	Array of approved scopes. For a list of possible values, see access token scopes

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

Request partner program details

Request received

Error