2020-07-15 00:09:23 +00:00
---
stage: Release
group: Progressive Delivery
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/#designated-technical-writers
---
2020-02-20 03:08:57 +00:00
# Deploy Tokens API
## List all deploy tokens
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-11 06:10:11 +00:00
2020-02-28 12:09:05 +00:00
Get a list of all deploy tokens across the GitLab instance. This endpoint requires admin access.
2020-02-20 03:08:57 +00:00
2020-02-28 12:09:05 +00:00
```plaintext
2020-02-20 03:08:57 +00:00
GET /deploy_tokens
```
2020-02-28 12:09:05 +00:00
Example request:
2020-02-20 03:08:57 +00:00
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
2020-02-28 12:09:05 +00:00
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
## Project deploy tokens
Project deploy token API endpoints require project maintainer access or higher.
### List project deploy tokens
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-11 06:10:11 +00:00
2020-02-28 12:09:05 +00:00
Get a list of a project's deploy tokens.
```plaintext
GET /projects/:id/deploy_tokens
```
Parameters:
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
Example request:
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
2020-02-20 03:08:57 +00:00
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
2020-03-09 00:08:14 +00:00
2020-03-10 09:08:10 +00:00
### Create a project deploy token
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-10 09:08:10 +00:00
Creates a new deploy token for a project.
2020-03-25 06:07:58 +00:00
```plaintext
2020-03-10 09:08:10 +00:00
POST /projects/:id/deploy_tokens
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `name` | string | yes | New deploy token's name |
2020-10-30 21:08:52 +00:00
| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2020-03-10 09:08:10 +00:00
| `username` | string | no | Username for deploy token. Default is `gitlab+deploy-token-{n}` |
2020-05-14 03:07:52 +00:00
| `scopes` | array of strings | yes | Indicates the deploy token scopes. Must be at least one of `read_repository` , `read_registry` , `write_registry` , `read_package_registry` , or `write_package_registry` . |
2020-03-10 09:08:10 +00:00
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/"
```
Example response:
```json
{
"id": 1,
"name": "My deploy token",
"username": "custom-user",
"expires_at": "2021-01-01T00:00:00.000Z",
"token": "jMRvtPNxrn3crTAGukpZ",
"scopes": [
"read_repository"
]
}
```
2020-03-12 12:09:17 +00:00
### Delete a project deploy token
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-12 12:09:17 +00:00
Removes a deploy token from the project.
2020-03-25 06:07:58 +00:00
```plaintext
2020-03-12 12:09:17 +00:00
DELETE /projects/:id/deploy_tokens/:token_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `token_id` | integer | yes | The ID of the deploy token |
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/13"
```
2020-03-09 00:08:14 +00:00
## Group deploy tokens
2020-07-01 21:08:51 +00:00
Group maintainers and owners can list group deploy
tokens. Only group owners can create and delete group deploy tokens.
2020-03-09 00:08:14 +00:00
2020-04-08 06:09:54 +00:00
### List group deploy tokens
2020-03-11 06:10:11 +00:00
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-11 06:10:11 +00:00
Get a list of a group's deploy tokens
2020-03-25 06:07:58 +00:00
```plaintext
2020-03-11 06:10:11 +00:00
GET /groups/:id/deploy_tokens
```
Parameters:
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
| `id` | integer/string | yes | ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ). |
Example request:
```shell
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/1/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
2020-03-11 21:09:19 +00:00
### Create a group deploy token
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-11 21:09:19 +00:00
Creates a new deploy token for a group.
2020-03-25 06:07:58 +00:00
```plaintext
2020-03-11 21:09:19 +00:00
POST /groups/:id/deploy_tokens
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `name` | string | yes | New deploy token's name |
2020-10-30 21:08:52 +00:00
| `expires_at` | datetime | no | Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2020-03-11 21:09:19 +00:00
| `username` | string | no | Username for deploy token. Default is `gitlab+deploy-token-{n}` |
2020-05-14 03:07:52 +00:00
| `scopes` | array of strings | yes | Indicates the deploy token scopes. Must be at least one of `read_repository` , `read_registry` , `write_registry` , `read_package_registry` , or `write_package_registry` . |
2020-03-11 21:09:19 +00:00
Example request:
```shell
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/"
```
Example response:
```json
{
"id": 1,
"name": "My deploy token",
"username": "custom-user",
"expires_at": "2021-01-01T00:00:00.000Z",
"token": "jMRvtPNxrn3crTAGukpZ",
"scopes": [
"read_registry"
]
}
```
2020-03-09 00:08:14 +00:00
### Delete a group deploy token
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-03-11 06:10:11 +00:00
2020-03-09 00:08:14 +00:00
Removes a deploy token from the group.
2020-03-25 06:07:58 +00:00
```plaintext
2020-03-09 00:08:14 +00:00
DELETE /groups/:id/deploy_tokens/:token_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](README.md#namespaced-path-encoding ) owned by the authenticated user |
| `token_id` | integer | yes | The ID of the deploy token |
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/13"
```