The GitLab Docs website is now available in Japanese!

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 or 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 Authorized groups and projects setting is enabled for the allowlist. If disabled, then all projects have access. This value shows whether the allowlist is currently active, which can be `true` due to the Enforce job token allowlist instance setting.
`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

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 or string	Yes	ID or URL-encoded path of the project.
`enabled`	boolean	Yes	Restricts job token access to allowlisted projects only. Set to `false` to allow access from all projects. This parameter can be overridden by the Enforce job token allowlist instance setting.

If successful, returns 204 and no response body.

If the Enforce job token allowlist instance setting is enabled and you attempt to set enabled to false, returns 400 with an error message.

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 or 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 or 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:

{
  "source_project_id": 1,
  "target_project_id": 2
}

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

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

DELETE /projects/:id/job_token_scope/allowlist/:target_project_id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`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 and no response body.

Example request:

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

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.

GET /projects/:id/job_token_scope/groups_allowlist

Supported attributes:

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

This endpoint supports offset-based pagination.

If successful, returns 200 and a list of groups 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/groups_allowlist"

Example response:

[
  {
    "id": 4,
    "web_url": "https://gitlab.example.com/groups/diaspora/diaspora-group",
    "name": "namegroup"
  },
  {
    ...
  }
]

Add a group to a CI/CD job token allowlist

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

POST /projects/:id/job_token_scope/groups_allowlist

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`target_group_id`	integer	Yes	The ID of the group added to the CI/CD job token groups 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_group_id`	integer	ID of the group that is added to the source project’s groups allowlist.

Example request:

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

Example response:

{
  "source_project_id": 1,
  "target_group_id": 2
}

Remove a group from a CI/CD job token allowlist

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

DELETE /projects/:id/job_token_scope/groups_allowlist/:target_group_id

Supported attributes:

Attribute	Type	Required	Description
`id`	integer or string	Yes	ID or URL-encoded path of the project.
`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 and no response body.

Example request:

curl --request DELETE \
  --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope/groups_allowlist/2" \
  --header 'PRIVATE-TOKEN: <your_access_token>' \
  --header 'Content-Type: application/json'