Deploy Tokens API

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

List all deploy tokens

DETAILS: Tier: Free, Premium, Ultimate Offering: GitLab Self-Managed, GitLab Dedicated

Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access.

GET /deploy_tokens

Parameters:

Attribute	Type	Required	Description
`active`	boolean	No	Limit by active status.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"

Example response:

[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Project deploy tokens

Project deploy token API endpoints require at least the Maintainer role for the project.

List project deploy tokens

Get a list of a project's deploy tokens.

GET /projects/:id/deploy_tokens

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project.
`active`	boolean	No	Limit by active status.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deploy_tokens"

Example response:

[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Get a project deploy token

Get a single project's deploy token by ID.

GET /projects/:id/deploy_tokens/:token_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project
`token_id`	integer	Yes	ID of the deploy token

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deploy_tokens/1"

Example response:

{
  "id": 1,
  "name": "MyToken",
  "username": "gitlab+deploy-token-1",
  "expires_at": "2020-02-14T00:00:00.000Z",
  "revoked": false,
  "expired": false,
  "scopes": [
    "read_repository",
    "read_registry"
  ]
}

Create a project deploy token

Creates a new deploy token for a project.

POST /projects/:id/deploy_tokens

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project
`name`	string	Yes	New deploy token's name
`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`.
`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`)
`username`	string	No	Username for deploy token. Default is `gitlab+deploy-token-{n}`

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```0

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```1

### Delete a project deploy token

Removes a deploy token from the project.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```2

Parameters:

| Attribute  | Type           | Required               | Description |
| ---------- | -------------- | ---------------------- | ----------- |
| `id`       | integer/string | Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-paths) |
| `token_id` | integer        | Yes | ID of the deploy token |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```3

## Group deploy tokens

Users with at least the Maintainer role for the group can list group deploy
tokens. Only group Owners can create and delete group deploy tokens.

### List group deploy tokens

Get a list of a group's deploy tokens

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```4

Parameters:

| Attribute      | Type           | Required               | Description |
|:---------------|:---------------|:-----------------------|:------------|
| `id`           | integer/string | Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-paths). |
| `active`       | boolean        | No | Limit by active status. |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```5

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```6

### Get a group deploy token

Get a single group's deploy token by ID.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```7

Parameters:

| Attribute   | Type           | Required               | Description |
| ----------- | -------------- | ---------------------- | ----------- |
| `id`        | integer/string | Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-paths) |
| `token_id`  | integer        | Yes | ID of the deploy token |

Example request:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```8

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```9

### Create a group deploy token

Creates a new deploy token for a group.

```json
[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]
```0

Parameters:

| Attribute    | Type | Required  | Description |
| ------------ | ---- | --------- | ----------- |
| `id`         | integer/string   | Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-paths) |
| `name`       | string           | Yes | New deploy token's name |
| `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`. |
| `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`) |
| `username`   | string           | No | Username for deploy token. Default is `gitlab+deploy-token-{n}` |

Example request:

```json
[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]
```1

Example response:

```json
[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]
```2

### Delete a group deploy token

Removes a deploy token from the group.

```json
[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]
```3

Parameters:

| Attribute   | Type           | Required               | Description |
| ----------- | -------------- | ---------------------- | ----------- |
| `id`        | integer/string | Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-paths) |
| `token_id`  | integer        | Yes | ID of the deploy token |

Example request:

```json
[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]
```4