2020-07-15 00:09:23 +00:00
---
stage: Release
2020-12-01 15:09:28 +00:00
group: Release
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-15 00:09:23 +00:00
---
2021-09-09 15:09:24 +00:00
# Deploy keys API **(FREE)**
2013-06-06 10:19:23 +00:00
2022-07-04 12:09:33 +00:00
The deploy keys API can return in responses fingerprints of the public key in the following fields:
- `fingerprint` (MD5 hash). Not available on FIPS-enabled systems.
- `fingerprint_sha256` (SHA256 hash). [Introduced ](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/91302 ) in GitLab 15.2.
2021-09-09 15:09:24 +00:00
## List all deploy keys **(FREE SELF)**
2016-06-02 02:25:22 +00:00
2021-08-27 00:08:45 +00:00
Get a list of all deploy keys across all projects of the GitLab instance. This
2022-02-02 15:17:50 +00:00
endpoint requires administrator access and is not available on GitLab.com.
2016-06-02 02:25:22 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2016-06-02 02:25:22 +00:00
GET /deploy_keys
```
2021-11-02 06:10:00 +00:00
Supported attributes:
| Attribute | Type | Required | Description |
|:------------|:---------|:---------|:----------------------|
| `public` | boolean | ** {dotted-circle}** No | Only return deploy keys that are public. Defaults to `false` . |
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-11-02 06:10:00 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/deploy_keys?public=true"
2016-06-02 02:25:22 +00:00
```
Example response:
```json
[
{
"id": 1,
"title": "Public key",
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==",
"fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
"fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
2021-11-02 06:10:00 +00:00
"created_at": "2013-10-02T10:12:29Z",
"projects_with_write_access": [
{
"id": 73,
"description": null,
"name": "project2",
"name_with_namespace": "Sidney Jones / project2",
"path": "project2",
"path_with_namespace": "sidney_jones/project2",
"created_at": "2021-10-25T18:33:17.550Z"
},
{
"id": 74,
"description": null,
"name": "project3",
"name_with_namespace": "Sidney Jones / project3",
"path": "project3",
"path_with_namespace": "sidney_jones/project3",
"created_at": "2021-10-25T18:33:17.666Z"
}
]
2016-06-02 02:25:22 +00:00
},
{
"id": 3,
"title": "Another Public key",
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDIJFwIL6YNcCgVBLTHgM6hzmoL5vf0ThDKQMWT3HrwCjUCGPwR63vBwn6+/Gx+kx+VTo9FuojzR0O4XfwD3LrYA+oT3ETbn9U4e/VS4AH/G4SDMzgSLwu0YuPe517FfGWhWGQhjiXphkaQ+6bXPmcASWb0RCO5+pYlGIfxv4eFGQ=="
"fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75",
"fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims",
2021-11-02 06:10:00 +00:00
"created_at": "2013-10-02T11:12:29Z",
"projects_with_write_access": []
2016-06-02 02:25:22 +00:00
}
]
```
2022-06-15 00:09:28 +00:00
## List deploy keys for project
2013-06-06 10:19:23 +00:00
Get a list of a project's deploy keys.
2020-02-27 09:09:01 +00:00
```plaintext
2016-06-02 02:25:22 +00:00
GET /projects/:id/deploy_keys
2013-06-06 10:19:23 +00:00
```
2016-01-18 08:16:14 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 08:16:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/deploy_keys"
2016-01-18 08:16:14 +00:00
```
2013-06-06 10:19:23 +00:00
2016-01-18 08:16:14 +00:00
Example response:
2013-06-06 10:19:23 +00:00
```json
[
{
"id": 1,
2014-04-05 06:36:47 +00:00
"title": "Public key",
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==",
"fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
"fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
2018-01-05 15:23:44 +00:00
"created_at": "2013-10-02T10:12:29Z",
"can_push": false
2013-06-06 10:19:23 +00:00
},
{
"id": 3,
2014-04-05 06:36:47 +00:00
"title": "Another Public key",
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDIJFwIL6YNcCgVBLTHgM6hzmoL5vf0ThDKQMWT3HrwCjUCGPwR63vBwn6+/Gx+kx+VTo9FuojzR0O4XfwD3LrYA+oT3ETbn9U4e/VS4AH/G4SDMzgSLwu0YuPe517FfGWhWGQhjiXphkaQ+6bXPmcASWb0RCO5+pYlGIfxv4eFGQ=="
"fingerprint": "0b:cf:58:40:b9:23:96:c7:ba:44:df:0e:9e:87:5e:75",
"fingerprint_sha256": "SHA256:lGI/Ys/Wx7PfMhUO1iuBH92JQKYN+3mhJZvWO4Q5ims",
2018-01-05 15:23:44 +00:00
"created_at": "2013-10-02T11:12:29Z",
"can_push": false
2013-06-06 10:19:23 +00:00
}
]
```
2022-06-15 00:09:28 +00:00
## List project deploy keys for user
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88917) in GitLab 15.1.
Get a list of a specified user (requestee) and the authenticated user's (requester) common [project deploy keys ](../user/project/deploy_keys/index.md#scope ). It lists only the **enabled project keys from the common projects of requester and requestee** .
```plaintext
GET /users/:id_or_username/project_deploy_keys
```
Parameters:
| Attribute | Type | Required | Description |
|------------------- |--------|----------|------------------------------------------------------------------- |
| `id_or_username` | string | yes | The ID or username of the user to get the project deploy keys for. |
```json
[
{
"id": 1,
"title": "Key A",
"created_at": "2022-05-30T12:28:27.855Z",
"expires_at": null,
2022-07-04 12:09:33 +00:00
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILkYXU2fVeO4/0rDCSsswP5iIX2+B6tv15YT3KObgyDl Key",
"fingerprint": "40:8e:fa:df:70:f7:a7:06:1e:0d:6f:ae:f2:27:92:01",
"fingerprint_sha256": "SHA256:Ojq2LZW43BFK/AMP81jBkDGn9YpPWYRNcViKBB44LPU"
2022-06-15 00:09:28 +00:00
},
{
"id": 2,
"title": "Key B",
"created_at": "2022-05-30T13:34:56.219Z",
"expires_at": null,
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==",
"fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
"fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
2022-06-15 00:09:28 +00:00
}
]
```
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/users/20/project_deploy_keys"
```
Example response:
```json
[
{
"id": 1,
"title": "Key A",
"created_at": "2022-05-30T12:28:27.855Z",
"expires_at": "2022-10-30T12:28:27.855Z",
2022-07-04 12:09:33 +00:00
"key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILkYXU2fVeO4/0rDCSsswP5iIX2+B6tv15YT3KObgyDl Key",
"fingerprint": "40:8e:fa:df:70:f7:a7:06:1e:0d:6f:ae:f2:27:92:01",
"fingerprint_sha256": "SHA256:Ojq2LZW43BFK/AMP81jBkDGn9YpPWYRNcViKBB44LPU"
2022-06-15 00:09:28 +00:00
}
]
```
2021-08-27 00:08:45 +00:00
## Get a single deploy key
2013-06-06 10:19:23 +00:00
Get a single key.
2020-02-27 09:09:01 +00:00
```plaintext
2016-06-02 02:25:22 +00:00
GET /projects/:id/deploy_keys/:key_id
2013-06-06 10:19:23 +00:00
```
Parameters:
2016-01-18 08:16:14 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 08:16:14 +00:00
| `key_id` | integer | yes | The ID of the deploy key |
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11"
2016-01-18 08:16:14 +00:00
```
Example response:
2013-06-06 10:19:23 +00:00
```json
{
"id": 1,
2014-04-05 06:36:47 +00:00
"title": "Public key",
2022-07-04 12:09:33 +00:00
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDNJAkI3Wdf0r13c8a5pEExB2YowPWCSVzfZV22pNBc1CuEbyYLHpUyaD0GwpGvFdx2aP7lMEk35k6Rz3ccBF6jRaVJyhsn5VNnW92PMpBJ/P1UebhXwsFHdQf5rTt082cSxWuk61kGWRQtk4ozt/J2DF/dIUVaLvc+z4HomT41fQ==",
"fingerprint": "4a:9d:64:15:ed:3a:e6:07:6e:89:36:b3:3b:03:05:d9",
"fingerprint_sha256": "SHA256:Jrs3LD1Ji30xNLtTVf9NDCj7kkBgPBb2pjvTZ3HfIgU",
2018-01-05 15:23:44 +00:00
"created_at": "2013-10-02T10:12:29Z",
"can_push": false
2013-06-06 10:19:23 +00:00
}
```
2014-04-24 22:48:22 +00:00
## Add deploy key
2013-06-06 10:19:23 +00:00
Creates a new deploy key for a project.
2016-01-18 08:16:14 +00:00
2020-12-17 21:09:57 +00:00
If the deploy key already exists in another project, it's joined to the current
project only if the original one is accessible by the same user.
2013-06-06 10:19:23 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2016-06-02 02:25:22 +00:00
POST /projects/:id/deploy_keys
2013-06-06 10:19:23 +00:00
```
2016-08-18 07:27:45 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-08-18 07:27:45 +00:00
| `title` | string | yes | New deploy key's title |
| `key` | string | yes | New deploy key |
| `can_push` | boolean | no | Can deploy key push to the project's repository |
2016-01-18 08:16:14 +00:00
2020-01-30 15:09:15 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" \
--data '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \
"https://gitlab.example.com/api/v4/projects/5/deploy_keys/"
2016-01-18 08:16:14 +00:00
```
2013-06-06 10:19:23 +00:00
2016-01-18 08:16:14 +00:00
Example response:
```json
{
"key" : "ssh-rsa AAAA...",
"id" : 12,
"title" : "My deploy key",
2016-08-18 07:27:45 +00:00
"can_push": true,
2016-01-18 08:16:14 +00:00
"created_at" : "2015-08-29T12:44:31.550Z"
}
```
2013-06-06 10:19:23 +00:00
2018-01-05 15:23:44 +00:00
## Update deploy key
Updates a deploy key for a project.
2020-02-27 09:09:01 +00:00
```plaintext
2018-01-05 15:23:44 +00:00
PUT /projects/:id/deploy_keys/:key_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2018-01-05 15:23:44 +00:00
| `title` | string | no | New deploy key's title |
| `can_push` | boolean | no | Can deploy key push to the project's repository |
2020-01-30 15:09:15 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request PUT --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" \
--data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11"
2018-01-05 15:23:44 +00:00
```
Example response:
```json
{
"id": 11,
"title": "New deploy key",
"key": "ssh-rsa AAAA...",
"created_at": "2015-08-29T12:44:31.550Z",
"can_push": true
}
```
2014-04-24 22:48:22 +00:00
## Delete deploy key
2013-06-06 10:19:23 +00:00
2020-12-17 21:09:57 +00:00
Removes a deploy key from the project. If the deploy key is used only for this project, it's deleted from the system.
2013-06-06 10:19:23 +00:00
2020-02-27 09:09:01 +00:00
```plaintext
2016-06-02 02:25:22 +00:00
DELETE /projects/:id/deploy_keys/:key_id
2013-06-06 10:19:23 +00:00
```
2016-01-18 08:16:14 +00:00
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-01-18 08:16:14 +00:00
| `key_id` | integer | yes | The ID of the deploy key |
2020-01-30 15:09:15 +00:00
```shell
2018-12-27 09:03:08 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/deploy_keys/13"
2016-01-18 08:16:14 +00:00
```
2013-06-06 10:19:23 +00:00
2016-08-03 12:45:32 +00:00
## Enable a deploy key
Enables a deploy key for a project so this can be used. Returns the enabled key, with a status code 201 when successful.
2022-06-09 03:08:17 +00:00
```plaintext
POST /projects/:id/deploy_keys/:key_id/enable
2016-08-03 12:45:32 +00:00
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-06-28 15:08:03 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) owned by the authenticated user |
2016-08-03 12:45:32 +00:00
| `key_id` | integer | yes | The ID of the deploy key |
2022-06-09 03:08:17 +00:00
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/deploy_keys/12/enable"
```
2016-08-03 12:45:32 +00:00
Example response:
```json
{
"key" : "ssh-rsa AAAA...",
"id" : 12,
"title" : "My deploy key",
"created_at" : "2015-08-29T12:44:31.550Z"
}
```
2019-08-22 08:50:31 +00:00
2021-08-27 00:08:45 +00:00
## Add deploy keys to multiple projects
2019-08-08 05:45:13 +00:00
2021-08-27 00:08:45 +00:00
If you want to add the same deploy key to multiple projects in the same
group, this can be achieved with the API.
2019-08-08 05:45:13 +00:00
First, find the ID of the projects you're interested in, by either listing all
projects:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects"
2019-08-08 05:45:13 +00:00
```
2019-08-30 06:19:01 +00:00
Or finding the ID of a group:
2019-08-08 05:45:13 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups"
2019-08-30 06:19:01 +00:00
```
2019-08-08 05:45:13 +00:00
2019-08-30 06:19:01 +00:00
Then listing all projects in that group (for example, group 1234):
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/1234"
2019-08-08 05:45:13 +00:00
```
With those IDs, add the same deploy key to all:
2020-01-30 15:09:15 +00:00
```shell
2019-08-08 05:45:13 +00:00
for project_id in 321 456 987; do
2021-06-02 15:09:59 +00:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " \
--header "Content-Type: application/json" \
--data '{"title": "my key", "key": "ssh-rsa AAAA..."}' \
"https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys"
2019-08-08 05:45:13 +00:00
done
```