Skip to content

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
    }
  ]
}