Files
gitlab-foss/doc/api/project_job_token_scopes.md
2025-06-02 09:18:46 +00:00

11 KiB

stage, group, info, title
stage group info title
Software Supply Chain Security Pipeline Security To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments CI/CD job token scope API

{{< details >}}

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

{{< /details >}}

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

{{< alert type="note" >}}

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.

{{< /alert >}}

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 >}}

  • 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.

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