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

History

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:

{
  "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/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/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/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/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'

Post on the GitLab forum

CI/CD job token scope API

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

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

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

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

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

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

Add a group to a CI/CD job token allowlist

Remove a group from a CI/CD job token allowlist

Help & feedback