Keys

Use this API to retrieve information about SSH keys, manage a user’s SSH and GPG keys, and manage SSH certificates for top-level groups.

Queries about deploy key fingerprints also retrieve information about the projects using that key. If you use a SHA256 fingerprint in an API call, URL-encode the fingerprint.

Managing group SSH certificates requires the Owner role for a top-level group.

Retrieve user by SSH key fingerprint

GET /api/v4/keys

Retrieves user by SSH key fingerprint. Administrators only.

Parameters

Name	Type	Description
`fingerprint` Query, required	String	The fingerprint of an SSH key Example: `ba:81:59:68:d7:6c:cd:02:02:bf:6a:9b:55:4e:af:d1`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesUserWithAdmin
`400`	Bad Request	—

Retrieve user by SSH key ID

GET /api/v4/keys/{id}

Retrieves user by SSH key ID. Administrators only.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID of an SSH key Example: `2`

Responses

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

List all GPG keys

GET /api/v4/user/gpg_keys

Lists all GPG keys for the currently authenticated user.

Parameters

Name	Type	Description
`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	APIEntitiesGpgKey
`400`	Bad Request	—

Add a GPG key

POST /api/v4/user/gpg_keys

Adds a GPG key for the currently authenticated user.

Request body (application/json)

Property	Type	Description
`key` Required	String	The new GPG key

Responses

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

Retrieve a GPG key

GET /api/v4/user/gpg_keys/{key_id}

Retrieves a GPG key for the currently authenticated user.

Parameters

Name	Type	Description
`key_id` Path, required	Integer	The ID of the GPG key

Responses

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

Delete a GPG key

DELETE /api/v4/user/gpg_keys/{key_id}

Deletes a GPG key from your user account.

Parameters

Name	Type	Description
`key_id` Path, required	Integer	The ID of the SSH key

Responses

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

List all SSH keys

GET /api/v4/user/keys

Lists all SSH keys for the currently authenticated user.

Parameters

Name	Type	Description
`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	APIEntitiesSSHKey
`400`	Bad Request	—

Add an SSH key

POST /api/v4/user/keys

Adds an SSH key for the currently authenticated user.

Request body (application/json)

Property	Type	Description
`expires_at`	String (date-time)	The expiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
`key` Required	String	The new SSH key
`title` Required	String	The title of the new SSH key
`usage_type`	String	Scope of usage for the SSH key Allowed values: `auth_and_signing`, `auth`, `signing` Default: `auth_and_signing`

Responses

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

Retrieve an SSH key

GET /api/v4/user/keys/{key_id}

Retrieves a specified SSH key for the currently authenticated user.

Parameters

Name	Type	Description
`key_id` Path, required	Integer	The ID of the SSH key

Responses

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

Delete an SSH key

DELETE /api/v4/user/keys/{key_id}

Deletes a specified SSH key from the currently authenticated user.

Parameters

Name	Type	Description
`key_id` Path, required	Integer	The ID of the SSH key

Responses

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

List all GPG keys for a user

GET /api/v4/users/{id}/gpg_keys

Lists all GPG keys for a specified user account. This endpoint does not require authentication.

Parameters

Name	Type	Description
`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`

Responses

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

Retrieve a GPG key for a user

GET /api/v4/users/{id}/gpg_keys/{key_id}

Retrieves a GPG key for a specified user account. This endpoint does not require authentication.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of the user
`key_id` Path, required	Integer	The ID of the GPG key

Responses

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

Delete a GPG key for a user

DELETE /api/v4/users/{id}/gpg_keys/{key_id}

Deletes a GPG key from a specified user account. Administrators only.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of the user
`key_id` Path, required	Integer	The ID of the GPG key

Responses

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

Retrieve an SSH key for a user

GET /api/v4/users/{id}/keys/{key_id}

Retrieves an SSH key for a specified user account. This endpoint does not require authentication.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of the user
`key_id` Path, required	Integer	The ID of the SSH key

Responses

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

Delete an SSH key for a user

DELETE /api/v4/users/{id}/keys/{key_id}

Deletes an SSH key from a specified user account. Administrators only.

Parameters

Name	Type	Description
`id` Path, required	Integer	The ID of the user
`key_id` Path, required	Integer	The ID of the SSH key

Responses

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

List all SSH keys for a user

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

Lists all SSH keys for a specified user account.

Parameters

Name	Type	Description
`user_id` Path, required	String	The ID or username 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`

Responses

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

Add an SSH key for a user

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

Adds an SSH key for a specified user account. Administrators only.

Parameters

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

Request body (application/json)

Property	Type	Description
`expires_at`	String (date-time)	The expiration date of the SSH key in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
`key` Required	String	The new SSH key
`title` Required	String	The title of the new SSH key
`usage_type`	String	Scope of usage for the SSH key Allowed values: `auth_and_signing`, `auth`, `signing` Default: `auth_and_signing`

Responses

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

Schemas

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

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesGpgKey

Property	Type	Description
`created_at`	String (date-time)	Example: `2017-09-05T09:17:46.264Z`
`id`	Integer (int64)	Example: `1`
`key`	String	Example: `-----BEGIN PGP PUBLIC KEY BLOCK-----`

APIEntitiesIdentity

Property	Type	Description
`extern_uid`	String	—
`provider`	String	—

APIEntitiesSSHKey

Property	Type	Description
`created_at`	String (date-time)	Example: `2015-09-03T07:24:44.627Z`
`expires_at`	String (date-time)	Example: `2020-09-03T07:24:44.627Z`
`id`	Integer (int64)	Example: `1`
`key`	String	Example: `ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6Yjz\ GGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCdd\ NaP0L+hM7zhFNzjFvpaMgJw0=`
`last_used_at`	String (date-time)	Example: `2020-09-03T07:24:44.627Z`
`title`	String	Example: `Sample key 25`
`usage_type`	String	Example: `auth`

APIEntitiesSSHKeyWithUser

Property	Type	Description
`created_at`	String (date-time)	Example: `2015-09-03T07:24:44.627Z`
`expires_at`	String (date-time)	Example: `2020-09-03T07:24:44.627Z`
`id`	Integer (int64)	Example: `1`
`key`	String	Example: `ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6Yjz\ GGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCdd\ NaP0L+hM7zhFNzjFvpaMgJw0=`
`last_used_at`	String (date-time)	Example: `2020-09-03T07:24:44.627Z`
`title`	String	Example: `Sample key 25`
`usage_type`	String	Example: `auth`
`user`	APIEntitiesUserPublic	—

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

APIEntitiesUserPublic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`bio`	String	—
`bot`	Boolean	—
`can_create_group`	Boolean	Example: `true`
`can_create_project`	Boolean	Example: `true`
`color_scheme_id`	Integer	Example: `1`
`commit_email`	String	—
`confirmed_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`created_at`	String	—
`current_sign_in_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`discord`	String	—
`email`	String	Example: `john@example.com`
`external`	Boolean	—
`followers`	String	—
`following`	String	—
`github`	String	—
`id`	Integer (int64)	Example: `1`
`identities`	APIEntitiesIdentity	—
`is_followed`	String	—
`job_title`	String	—
`last_activity_on`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`last_sign_in_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`linkedin`	String	—
`local_time`	String	—
`location`	String	—
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`organization`	String	—
`preferred_language`	String	Example: `en`
`private_profile`	Boolean	Example: `false`
`projects_limit`	Integer	Example: `10`
`pronouns`	String	—
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`theme_id`	Integer	Example: `2`
`twitter`	String	—
`two_factor_enabled`	Boolean	Example: `true`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`
`website_url`	String	—
`work_information`	String	—

APIEntitiesUserWithAdmin

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`bio`	String	—
`bot`	Boolean	—
`can_create_group`	Boolean	Example: `true`
`can_create_project`	Boolean	Example: `true`
`color_scheme_id`	Integer	Example: `1`
`commit_email`	String	—
`confirmed_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`created_at`	String	—
`created_by`	APIEntitiesUserBasic	—
`current_sign_in_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`discord`	String	—
`email`	String	Example: `john@example.com`
`external`	Boolean	—
`followers`	String	—
`following`	String	—
`github`	String	—
`id`	Integer (int64)	Example: `1`
`identities`	APIEntitiesIdentity	—
`is_admin`	String	—
`is_followed`	String	—
`job_title`	String	—
`last_activity_on`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`last_sign_in_at`	String (date-time)	Example: `2015-09-03T07:24:01.670Z`
`linkedin`	String	—
`local_time`	String	—
`location`	String	—
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`namespace_id`	String	—
`note`	String	—
`organization`	String	—
`preferred_language`	String	Example: `en`
`private_profile`	Boolean	Example: `false`
`projects_limit`	Integer	Example: `10`
`pronouns`	String	—
`provisioned_by_project_id`	String	—
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`theme_id`	Integer	Example: `2`
`twitter`	String	—
`two_factor_enabled`	Boolean	Example: `true`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`
`website_url`	String	—
`work_information`	String	—

Retrieve user by SSH key fingerprint

Retrieve user by SSH key ID

List all GPG keys

Add a GPG key

Retrieve a GPG key

Delete a GPG key

List all SSH keys

Add an SSH key

Retrieve an SSH key

Delete an SSH key

List all GPG keys for a user

Retrieve a GPG key for a user

Delete a GPG key for a user

Retrieve an SSH key for a user

Delete an SSH key for a user

List all SSH keys for a user

Add an SSH key for a user

Schemas

APIEntitiesCustomAttribute

APIEntitiesGpgKey

APIEntitiesIdentity

APIEntitiesSSHKey

APIEntitiesSSHKeyWithUser

APIEntitiesUserBasic

APIEntitiesUserPublic

APIEntitiesUserWithAdmin

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