Tokens API

9 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.

Endpoints

GET /api/v1/admin/tokens

List all API tokens

List all API tokens across users (admin only)

Parameters

Name	In	Type	Required	Description
page	query	integer	no	Minimum: 1.
per_page	query	integer	no	Minimum: 1. Maximum: 100.

Responses

Status	Description	Body
200	Paginated list of tokens	application/json: object
400	Invalid request	application/json: Error
403	Admin access required	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of AdminToken	no	-
page	integer	no	-
per_page	integer	no	-
total	integer	no	-

DELETE /api/v1/admin/tokens/{tokenId}

Revoke any API token

Revoke any user's API token (admin only)

Parameters

Name	In	Type	Required	Description
tokenId	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	Token revoked	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Token not found	-

GET /api/v1/auth/tokens

List own API tokens

List API tokens for the current user

Responses

Status	Description	Body
200	List of tokens	application/json: object
403	Forbidden	application/json: Error

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of Token	no	-

POST /api/v1/auth/tokens

Create own API token

Create a new API token for the current user

Request body (required)

application/json: object

Field	Type	Required	Description
expires_at	string (date-time)	no	-
kind	string	yes	One of: access, deploy.
name	string	yes	-
scopes	array of string	no	-

Responses

Status	Description	Body
201	Token created	application/json: TokenCreateResponse
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error

DELETE /api/v1/auth/tokens/{id}

Revoke own API token

Revoke an API token for the current user

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	Token revoked	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Token not found	-

GET /api/v1/tokens

List tokens

Personal, project and federation tokens in one list, newest first. A global admin sees every token; anyone else sees their own personal tokens plus the project and federation tokens of the projects they maintain or own. Secrets are never returned and revoked tokens are not listed. A non-admin needs an interactive session (an API token gets 403). Revoke with the per-type endpoints: DELETE /api/v1/auth/tokens/{id} (own personal), DELETE /api/v1/admin/tokens/{tokenId} (admin, any personal or project token), DELETE /api/v1/projects/{project}/tokens/{tokenId} and DELETE /api/v1/repositories/{name}/federation/tokens/{tokenId}.

Parameters

Name	In	Type	Required	Description
type	query	string	no	One of: personal, project, federation.
project	query	string	no	Project name: only that project's tokens and the federation tokens of its repositories (personal tokens never match).
expires_before	query	string	no	RFC 3339 timestamp or YYYY-MM-DD date: only tokens that expire before it (already expired ones included; tokens without an expiry never match).
q	query	string	no	Case-insensitive substring of the token name or owner.
page	query	integer	no	Default: 1. Minimum: 1.
limit	query	integer	no	Default: 25. Minimum: 1. Maximum: 100.

Responses

Status	Description	Body
200	One page of tokens	application/json: UnifiedTokenList
400	Invalid type or expires_before	-
401	Not authenticated	-
403	A non-admin API token cannot list tokens	-

GET /api/v1/users/{id}/tokens

List user's tokens

List the active (not revoked) API tokens of a user (owner or admin)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Responses

Status	Description	Body
200	List of tokens	application/json: object
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	User not found	-

Fields of the 200 response (application/json):

Field	Type	Required	Description
data	array of Token	no	-

POST /api/v1/users/{id}/tokens

Create token for user

Create an API token for a user (admin only)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-

Request body (required)

application/json: object

Field	Type	Required	Description
expires_at	string (date-time)	no	-
kind	string	yes	One of: access, deploy.
name	string	yes	-
scopes	array of string	no	-

Responses

Status	Description	Body
201	Token created	application/json: TokenCreateResponse
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	The addressed resource was not found	application/json: Error

DELETE /api/v1/users/{id}/tokens/{tokenId}

Revoke user's token

Revoke an API token for a user (admin only)

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	-
tokenId	path	string (uuid)	yes	-

Responses

Status	Description	Body
204	Token revoked	-
400	Invalid request, including a NUL byte in the URL or the body	application/json: Error
403	Forbidden	application/json: Error
404	Token not found	-