Keys API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Use the keys API to identify the user associated with a SSH key, or its fingerprint. Queries about deploy key fingerprints also retrieve information about the projects using that key.
If you use a SHA256 fingerprint in an API call, you should URL-encode the fingerprint.
Get SSH key with user by ID
Prerequisites:
- You must have administrator access to the instance.
You can get an SSH key and information about the user who owns the key.
GET /keys/:id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer | Yes | ID of an SSH key. |
If successful, returns 200 OK
and the
following response attributes:
Attribute | Type | Description |
---|---|---|
created_at | string | Creation date and time of the SSH key in ISO 8601 format. |
expires_at | string | Expiration date and time of the SSH key in ISO 8601 format. |
id | integer | ID of the SSH key. |
key | string | SSH key content. |
last_used_at | string | Last usage date and time of the SSH key in ISO 8601 format. |
title | string | Title of the SSH key. |
usage_type | string | Usage type of the SSH key (for example, auth or auth_and_signing ). |
user | object | User associated with the SSH key. |
user.avatar_url | string | URL of the user’s avatar. |
user.bio | string | Biography of the user. |
user.created_at | string | Creation date and time of the user account in ISO 8601 format. |
user.id | integer | ID of the user. |
user.linkedin | string | LinkedIn profile URL of the user. |
user.location | string | Location of the user. |
user.name | string | Name of the user. |
user.organization | string | Organization of the user. |
user.public_email | string | Public email address of the user. |
user.state | string | State of the user. |
user.twitter | string | Twitter profile URL of the user. |
user.username | string | Username of the user. |
user.web_url | string | URL of the user’s profile. |
user.website_url | string | Website URL of the user. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/keys/1"
Example response:
{
"id": 1,
"title": "Sample key 25",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1256k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2015-09-03T07:24:44.627Z",
"expires_at": "2020-05-05T00:00:00.000Z",
"last_used_at": "2020-04-07T00:00:00.000Z",
"usage_type": "auth",
"user": {
"name": "John Smith",
"username": "john_smith",
"id": 25,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/cfa35b8cd2ec278026357769582fa563?s=40\u0026d=identicon",
"web_url": "http://localhost:3000/john_smith",
"created_at": "2015-09-03T07:24:01.670Z",
"bio": null,
"location": null,
"public_email": "john@example.com",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": null,
"last_sign_in_at": "2015-09-03T07:24:01.670Z",
"confirmed_at": "2015-09-03T07:24:01.670Z",
"last_activity_on": "2015-09-03",
"email": "john@example.com",
"theme_id": 2,
"color_scheme_id": 1,
"projects_limit": 10,
"current_sign_in_at": null,
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": false,
"external": false,
"private_profile": null
}
}
Get user by SSH key fingerprint
Prerequisites:
- You must have administrator access to the instance.
You can search for a user that owns a specific SSH key.
GET /keys
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
fingerprint | string | Yes | Fingerprint of an SSH key. |
If successful, returns 200 OK
and the
following response attributes:
Attribute | Type | Description |
---|---|---|
created_at | string | Creation date and time of the SSH key in ISO 8601 format. |
expires_at | string | Expiration date and time of the SSH key in ISO 8601 format. |
id | integer | ID of the SSH key. |
key | string | SSH key content. |
last_used_at | string | Last usage date and time of the SSH key in ISO 8601 format. |
title | string | Title of the SSH key. |
usage_type | string | Usage type of the SSH key (for example, auth or auth_and_signing ). |
user | object | User associated with the SSH key. |
user.avatar_url | string | URL of the user’s avatar. |
user.bio | string | Biography of the user. |
user.can_create_group | boolean | If true , the user can create groups. |
user.can_create_project | boolean | If true , the user can create projects. |
user.color_scheme_id | integer | Color scheme ID of the user. |
user.confirmed_at | string | Confirmation date and time of the user in ISO 8601 format. |
user.created_at | string | Creation date and time of the user account in ISO 8601 format. |
user.current_sign_in_at | string | Current sign-in date and time of the user in ISO 8601 format. |
user.email | string | Email address of the user. |
user.external | boolean | If true , the user is external. |
user.id | integer | ID of the user. |
user.identities | array | Identities associated with the user. |
user.last_activity_on | string | Last activity date of the user. |
user.last_sign_in_at | string | Last sign-in date and time of the user in ISO 8601 format. |
user.linkedin | string | LinkedIn profile URL of the user. |
user.location | string | Location of the user. |
user.name | string | Name of the user. |
user.organization | string | Organization of the user. |
user.private_profile | boolean | If true , the user’s profile is private. |
user.projects_limit | integer | Project limit of the user. |
user.public_email | string | Public email address of the user. |
user.state | string | State of the user account. |
user.theme_id | integer | Theme ID of the user. |
user.twitter | string | Twitter profile URL of the user. |
user.two_factor_enabled | boolean | If true , two-factor authentication is enabled for the user. |
user.username | string | Username of the user. |
user.web_url | string | URL of the user’s profile. |
user.website_url | string | Website URL of the user. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/keys?fingerprint=ba:81:59:68:d7:6c:cd:02:02:bf:6a:9b:55:4e:af:d1"
Example response:
{
"id": 1,
"title": "Sample key 1",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1016k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2019-11-14T15:11:13.222Z",
"expires_at": "2020-05-05T00:00:00.000Z",
"last_used_at": "2020-04-07T00:00:00.000Z",
"usage_type": "auth",
"user": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://0.0.0.0:3000/root",
"created_at": "2019-11-14T15:09:34.831Z",
"bio": null,
"location": null,
"public_email": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": null,
"last_sign_in_at": "2019-11-16T22:41:26.663Z",
"confirmed_at": "2019-11-14T15:09:34.575Z",
"last_activity_on": "2019-11-20",
"email": "admin@example.com",
"theme_id": 1,
"color_scheme_id": 1,
"projects_limit": 100000,
"current_sign_in_at": "2019-11-19T14:42:18.078Z",
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": false,
"external": false,
"private_profile": false,
"shared_runners_minutes_limit": null,
"extra_shared_runners_minutes_limit": null
}
}
Get user by deploy key fingerprint
Deploy keys are bound to the creating user. When you query with a deploy key fingerprint, you get additional information about the projects using that key.
GET /keys
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
fingerprint | string | Yes | Fingerprint of a deploy key. |
If successful, returns 200 OK
and the
following response attributes:
Attribute | Type | Description |
---|---|---|
created_at | string | Creation date and time of the deploy key in ISO 8601 format. |
deploy_keys_projects | array | Deploy key projects information. |
deploy_keys_projects[].can_push | boolean | If true , the deploy key can push to the project. |
deploy_keys_projects[].created_at | string | Creation date and time in ISO 8601 format. |
deploy_keys_projects[].deploy_key_id | integer | ID of the deploy key. |
deploy_keys_projects[].id | integer | ID of the deploy key project relationship. |
deploy_keys_projects[].project_id | integer | ID of the project. |
deploy_keys_projects[].updated_at | string | Last update date and time in ISO 8601 format. |
expires_at | string | Expiration date and time of the deploy key in ISO 8601 format. |
id | integer | ID of the deploy key. |
key | string | Deploy key content. |
last_used_at | string | Last usage date and time of the deploy key in ISO 8601 format. |
title | string | Title of the deploy key. |
usage_type | string | Usage type of the deploy key (for example, auth or auth_and_signing ). |
user | object | User associated with the deploy key. |
user.avatar_url | string | URL of the user’s avatar. |
user.bio | string | Biography of the user. |
user.can_create_group | boolean | If true , the user can create groups. |
user.can_create_project | boolean | If true , the user can create projects. |
user.color_scheme_id | integer | Color scheme ID of the user. |
user.confirmed_at | string | Confirmation date and time of the user in ISO 8601 format. |
user.created_at | string | Creation date and time of the user account in ISO 8601 format. |
user.current_sign_in_at | string | Current sign-in date and time of the user in ISO 8601 format. |
user.email | string | Email address of the user. |
user.external | boolean | If true , the user is external. |
user.extra_shared_runners_minutes_limit | integer | Extra shared runners minutes limit of the user. |
user.id | integer | ID of the user. |
user.identities | array | Identities associated with the user. |
user.last_activity_on | string | Last activity date of the user. |
user.last_sign_in_at | string | Last sign-in date and time of the user in ISO 8601 format. |
user.linkedin | string | LinkedIn profile URL of the user. |
user.location | string | Location of the user. |
user.name | string | Name of the user. |
user.organization | string | Organization of the user. |
user.private_profile | boolean | If true , the user’s profile is private. |
user.projects_limit | integer | Project limit of the user. |
user.public_email | string | Public email address of the user. |
user.shared_runners_minutes_limit | integer | Shared runners minutes limit of the user. |
user.state | string | State of the user account. |
user.theme_id | integer | Theme ID of the user. |
user.twitter | string | Twitter profile URL of the user. |
user.two_factor_enabled | boolean | If true , two-factor authentication is enabled for the user. |
user.username | string | Username of the user. |
user.web_url | string | URL of the user’s profile. |
user.website_url | string | Website URL of the user. |
Example request with MD5 fingerprint:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/keys?fingerprint=ba:81:59:68:d7:6c:cd:02:02:bf:6a:9b:55:4e:af:d1"
Example request with SHA256 fingerprint (URL-encoded):
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/keys?fingerprint=SHA256%3AnUhzNyftwADy8AH3wFY31tAKs7HufskYTte2aXo%2FlCg"
In the SHA256 example, /
is represented by %2F
and :
is represented by %3A
.
Example response:
{
"id": 1,
"title": "Sample key 1",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1016k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
"created_at": "2019-11-14T15:11:13.222Z",
"expires_at": "2020-05-05T00:00:00.000Z",
"last_used_at": "2020-04-07T00:00:00.000Z",
"usage_type": "auth",
"user": {
"id": 1,
"name": "Administrator",
"username": "root",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
"web_url": "http://0.0.0.0:3000/root",
"created_at": "2019-11-14T15:09:34.831Z",
"bio": null,
"location": null,
"public_email": "",
"linkedin": "",
"twitter": "",
"website_url": "",
"organization": null,
"last_sign_in_at": "2019-11-16T22:41:26.663Z",
"confirmed_at": "2019-11-14T15:09:34.575Z",
"last_activity_on": "2019-11-20",
"email": "admin@example.com",
"theme_id": 1,
"color_scheme_id": 1,
"projects_limit": 100000,
"current_sign_in_at": "2019-11-19T14:42:18.078Z",
"identities": [],
"can_create_group": true,
"can_create_project": true,
"two_factor_enabled": false,
"external": false,
"private_profile": false,
"shared_runners_minutes_limit": null,
"extra_shared_runners_minutes_limit": null
},
"deploy_keys_projects": [
{
"id": 1,
"deploy_key_id": 1,
"project_id": 1,
"created_at": "2020-01-09T07:32:52.453Z",
"updated_at": "2020-01-09T07:32:52.453Z",
"can_push": false
}
]
}