CI/CD job token scope API

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

Use this API to interact with CI/CD job token scopes.

All requests to the CI/CD job token scope API endpoint must be authenticated. The authenticated user must have at least the Maintainer role for the project.

Get a project's CI/CD job token access settings

Fetch the CI/CD job token access settings (job token scope) of a project.

GET /projects/:id/job_token_scope

Supported attributes:

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

If successful, returns 200 and the following response attributes:

Attribute	Type	Description
`inbound_enabled`	boolean	Indicates if the Limit access to this project setting is enabled. If disabled, then all projects have access.
`outbound_enabled`	boolean	Indicates if the CI/CD job token generated in this project has access to other projects. Deprecated and planned for removal in GitLab 18.0.

Example request:

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

Example response:

{
  "inbound_enabled": true,
  "outbound_enabled": false
}

Patch a project's CI/CD job token access settings

Version history

Renamed from Allow access to this project with a CI_JOB_TOKEN to Limit access to this project in GitLab 16.3.
Renamed from Limit access to this project to Authorized groups and projects in GitLab 17.2.

Patch the Authorized groups and projects setting (job token scope) of a project.

PATCH /projects/:id/job_token_scope

Supported attributes:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project.
`enabled`	boolean	Yes	The state of the Authorized groups and projects setting to select. Set to `true` to select the This project and any groups and projects in the allowlist option, and set to `false` to select All groups and projects.

If successful, returns 204 and no response body.

Example request:

curl --request PATCH \
  --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope" \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "enabled": false }'

Get a project's CI/CD job token inbound allowlist

Fetch the CI/CD job token inbound allowlist (job token scope) of a project.

GET /projects/:id/job_token_scope/allowlist

Supported attributes:

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

This endpoint supports offset-based pagination.

If successful, returns 200 and a list of project with limited fields for each project.

Example request:

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

Example response:

[
  {
    "id": 4,
    "description": null,
    "name": "Diaspora Client",
    "name_with_namespace": "Diaspora / Diaspora Client",
    "path": "diaspora-client",
    "path_with_namespace": "diaspora/diaspora-client",
    "created_at": "2013-09-30T13:46:02Z",
    "default_branch": "main",
    "tag_list": [
      "example",
      "disapora client"
    ],
    "topics": [
      "example",
      "disapora client"
    ],
    "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git",
    "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git",
    "web_url": "https://gitlab.example.com/diaspora/diaspora-client",
    "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png",
    "star_count": 0,
    "last_activity_at": "2013-09-30T13:46:02Z",
    "namespace": {
      "id": 2,
      "name": "Diaspora",
      "path": "diaspora",
      "kind": "group",
      "full_path": "diaspora",
      "parent_id": null,
      "avatar_url": null,
      "web_url": "https://gitlab.example.com/diaspora"
    }
  },
  {
    ...
  }

Add a project to a CI/CD job token inbound allowlist

Add a project to the CI/CD job token inbound allowlist of a project.

POST /projects/:id/job_token_scope/allowlist

Supported attributes:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project.
`target_project_id`	integer	Yes	The ID of the project added to the CI/CD job token inbound allowlist.

If successful, returns 201 and the following response attributes:

Attribute	Type	Description
`source_project_id`	integer	ID of the project containing the CI/CD job token inbound allowlist to update.
`target_project_id`	integer	ID of the project that is added to the source project's inbound allowlist.

Example request:

curl --request POST \
  --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope/allowlist" \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "target_project_id": 2 }'

Example response:

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

## Remove a project from a CI/CD job token inbound allowlist

Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#add-a-group-or-project-to-the-job-token-allowlist) of a project.

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

Supported attributes:

| Attribute           | Type           | Required | Description |
|---------------------|----------------|----------|-------------|
| `id`                | integer/string | Yes      | ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths). |
| `target_project_id` | integer        | Yes      | The ID of the project that is removed from the CI/CD job token inbound allowlist. |

If successful, returns [`204`](rest/troubleshooting.md#status-codes) and no response body.

Example request:

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

## Get a project's CI/CD job token allowlist of groups

Fetch the CI/CD job token allowlist of groups (job token scope) of a project.

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

Supported attributes:

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

This endpoint supports [offset-based pagination](rest/_index.md#offset-based-pagination).

If successful, returns [`200`](rest/troubleshooting.md#status-codes) and a list of groups with limited fields for each project.

Example request:

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

Example response:

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

## Add a group to a CI/CD job token allowlist

Add a group to the CI/CD job token allowlist of a project.

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

Supported attributes:

| Attribute         | Type           | Required | Description |
|-------------------|----------------|----------|-------------|
| `id`              | integer/string | Yes      | ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths). |
| `target_group_id` | integer        | Yes      | The ID of the group added to the CI/CD job token groups allowlist. |

If successful, returns [`201`](rest/troubleshooting.md#status-codes) and the following response attributes:

| Attribute           | Type    | Description |
|---------------------|---------|-------------|
| `source_project_id` | integer | ID of the project containing the CI/CD job token inbound allowlist to update. |
| `target_group_id`   | integer | ID of the group that is added to the source project's groups allowlist. |

Example request:

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

Example response:

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

## Remove a group from a CI/CD job token allowlist

Remove a group from the CI/CD job token allowlist of a project.

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

Supported attributes:

| Attribute         | Type           | Required | Description |
|-------------------|----------------|----------|-------------|
| `id`              | integer/string | Yes      | ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths). |
| `target_group_id` | integer        | Yes      | The ID of the group that is removed from the CI/CD job token groups allowlist. |

If successful, returns [`204`](rest/troubleshooting.md#status-codes) and no response body.

Example request:

```json
{
  "inbound_enabled": true,
  "outbound_enabled": false
}
```0