• Add new endpoints
• Authentication
• Git Authentication
  • Known consumers
• LFS Authentication
  • Known consumers
• Authorized Keys Check
  • Known consumers
• Get user for user ID or key
  • Known consumers
• Instance information
  • Known consumers
• Get new 2FA recovery codes using an SSH key
  • Known consumers
• Get new personal access-token
  • Known consumers
• Authenticate Error Tracking requests
  • Known consumers
• Incrementing counter on pre-receive
• PostReceive
• GitLab agent endpoints
  • GitLab agent information
  • GitLab agent project information
  • GitLab agent usage metrics
  • Create Starboard vulnerability
  • Resolve Starboard vulnerabilities
  • Scan Execution Policies
  • Policy Configuration
• Subscriptions
  • Create a subscription
  • Update a subscription
  • Retrieve a subscription
  • Known consumers
• Subscription add-on purchases (excluding storage and compute packs)
  • Create a subscription add-on purchase
  • Update a subscription add-on purchases
  • Retrieve a subscription add-on purchases
  • Known consumers
• Storage limit exclusions
  • Retrieve storage limit exclusions
  • Create a storage limit exclusion
  • Delete a storage limit exclusion
  • Known consumers
• Compute quota provisioning
  • Create an additional pack
  • Move additional packs
  • Known consumers
• Upcoming reconciliations
  • Update upcoming_reconciliations
  • Delete an upcoming_reconciliation
  • Known consumers
• Group SCIM API
  • Get a list of SCIM provisioned users
  • Get a single SCIM provisioned user
  • Create a SCIM provisioned user
  • Update a single SCIM provisioned user
  • Remove a single SCIM provisioned user
• Instance SCIM API
  • Get a list of SCIM provisioned users
  • Get a single SCIM provisioned user
  • Create a SCIM provisioned user
  • Update a single SCIM provisioned user
  • Remove a single SCIM provisioned user
  • Available filters
  • Available operations

Internal API

The internal API is used by different GitLab components, it cannot be used by other consumers. This documentation is intended for people working on the GitLab codebase.

This documentation does not yet include the internal API used by GitLab Pages.

Add new endpoints

API endpoints should be externally accessible by default, with proper authentication and authorization. Before adding a new internal endpoint, consider if the API would potentially be useful to the wider GitLab community and can be made externally accessible.

One reason we might favor internal API endpoints sometimes is when using such an endpoint requires internal data that external actors cannot have. For example, in the internal Pages API we might use a secret token that identifies a request as internal or sign a request with a public key that is not available to a wider community.

Another reason to separate something into an internal API is when request to such API endpoint should never go through an edge (public) load balancer. This way we can configure different rate limiting rules and policies around how the endpoint is being accessed, because we know that only internal requests can be made to that endpoint going through an internal load balancer.

Authentication

These methods are all authenticated using a shared secret. This secret is stored in a file at the path configured in config/gitlab.yml by default this is in the root of the rails app named .gitlab_shell_secret

To authenticate using that token, clients:

1. Read the contents of that file.
2. Use the file contents to generate a JSON Web Token (JWT).
3. Pass the JWT in the Gitlab-Shell-Api-Request header.

Git Authentication

This is called by Gitaly and GitLab Shell to check access to a repository.

• When called from GitLab Shell: No changes are passed, and the internal API replies with the information needed to pass the request on to Gitaly.
• When called from Gitaly in a pre-receive hook: The changes are passed and validated to determine if the push is allowed.

Calls are limited to 50 seconds each.

This endpoint is covered in more detail on its own page, due to the scope of what it covers.

POST /internal/allowed

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2&action=git-upload-pack&protocol=ssh" \
     "http://localhost:3001/api/v4/internal/allowed"

Example response:

{
  "status": true,
  "gl_repository": "project-3",
  "gl_project_path": "gnuwget/wget2",
  "gl_id": "user-1",
  "gl_username": "root",
  "git_config_options": [],
  "gitaly": {
    "repository": {
      "storage_name": "default",
      "relative_path": "@hashed/4e/07/4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce.git",
      "git_object_directory": "",
      "git_alternate_object_directories": [],
      "gl_repository": "project-3",
      "gl_project_path": "gnuwget/wget2"
    },
    "address": "unix:/Users/bvl/repos/gitlab/gitaly.socket",
    "token": null
  },
  "gl_console_messages": []
}

Known consumers

• Gitaly
• GitLab Shell

LFS Authentication

This is the endpoint that gets called from GitLab Shell to provide information for LFS clients when the repository is accessed over SSH.

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=11&project=gnuwget/wget2" "http://localhost:3001/api/v4/internal/lfs_authenticate"

{
  "username": "root",
  "lfs_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjp7ImFjdG9yIjoicm9vdCJ9LCJqdGkiOiIyYWJhZDcxZC0xNDFlLTQ2NGUtOTZlMi1mODllYWRiMGVmZTYiLCJpYXQiOjE1NzAxMTc2NzYsIm5iZiI6MTU3MDExNzY3MSwiZXhwIjoxNTcwMTE5NDc2fQ.g7atlBw1QMY7QEBVPE0LZ8ZlKtaRzaMRmNn41r2YITM",
  "repository_http_path": "http://localhost:3001/gnuwget/wget2.git",
  "expires_in": 1800
}

Known consumers

• GitLab Shell

Authorized Keys Check

This endpoint is called by the GitLab Shell authorized keys check. Which is called by OpenSSH or GitLab SSHD for fast SSH key lookup.

GET /internal/authorized_keys

Example request:

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/authorized_keys?key=<key>"

Example response:

{
  "id": 11,
  "title": "admin@example.com",
  "key": "ssh-rsa ...",
  "created_at": "2019-06-27T15:29:02.219Z"
}

Known consumers

• GitLab Shell

Get user for user ID or key

This endpoint is used when a user performs ssh git@gitlab.com. It discovers the user associated with an SSH key.

GET /internal/discover

Example request:

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/discover?key_id=7"

Example response:

{
  "id": 7,
  "name": "Dede Eichmann",
  "username": "rubi"
}

Known consumers

• GitLab Shell

Instance information

This gets some generic information about the instance. This is used by Geo nodes to get information about each other.

GET /internal/check

Example request:

curl --request GET --header "Gitlab-Shell-Api-Request: <JWT token>" "http://localhost:3001/api/v4/internal/check"

Example response:

{
  "api_version": "v4",
  "gitlab_version": "12.3.0-pre",
  "gitlab_rev": "d69c988e6a6",
  "redis": true
}

Known consumers

• GitLab Geo
• GitLab Shell’s bin/check
• Gitaly

Get new 2FA recovery codes using an SSH key

This is called from GitLab Shell and allows users to get new 2FA recovery codes based on their SSH key.

GET /internal/two_factor_recovery_codes

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "key_id=7" "http://localhost:3001/api/v4/internal/two_factor_recovery_codes"

Example response:

{
  "success": true,
  "recovery_codes": [
    "d93ee7037944afd5",
    "19d7b84862de93dd",
    "1e8c52169195bf71",
    "be50444dddb7ca84",
    "26048c77d161d5b7",
    "482d5c03d1628c47",
    "d2c695e309ce7679",
    "dfb4748afc4f12a7",
    "0e5f53d1399d7979",
    "af04d5622153b020"
  ]
}

Known consumers

• GitLab Shell

Get new personal access-token

This is called from GitLab Shell and allows users to generate a new personal access token.

POST /internal/personal_access_token

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "user_id=29&name=mytokenname&scopes[]=read_user&scopes[]=read_repository&expires_at=2020-07-24" \
     "http://localhost:3001/api/v4/internal/personal_access_token"

Example response:

{
  "success": true,
  "token": "Hf_79B288hRv_3-TSD1R",
  "scopes": ["read_user","read_repository"],
  "expires_at": "2020-07-24"
}

Known consumers

• GitLab Shell

Authenticate Error Tracking requests

This endpoint is called by the error tracking Go REST API application to authenticate a project. > Introduced in GitLab 15.1.

POST /internal/error_tracking/allowed

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "project_id=111&public_key=generated-error-tracking-key" \
          "http://localhost:3001/api/v4/internal/error_tracking/allowed"

Example response:

{ "enabled": true }

Known consumers

• OpsTrace

Incrementing counter on pre-receive

This is called from the Gitaly hooks increasing the reference counter for a push that might be accepted.

POST /internal/pre_receive

Example request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" "http://localhost:3001/api/v4/internal/pre_receive"

Example response:

{
  "reference_counter_increased": true
}

PostReceive

Called from Gitaly after a receiving a push. This triggers the PostReceive-worker in Sidekiq, processes the passed push options and builds the response including messages that need to be displayed to the user.

POST /internal/post_receive

Example Request:

curl --request POST --header "Gitlab-Shell-Api-Request: <JWT token>" \
     --data "gl_repository=project-7" --data "identifier=user-1" \
     --data "changes=0000000000000000000000000000000000000000 fd9e76b9136bdd9fe217061b497745792fe5a5ee gh-pages\n" \
     "http://localhost:3001/api/v4/internal/post_receive"

Example response:

{
  "messages": [
    {
      "message": "Hello from post-receive",
      "type": "alert"
    }
  ],
  "reference_counter_decreased": true
}

GitLab agent endpoints

The following endpoints are used by the GitLab agent server (kas) for various purposes.

These endpoints are all authenticated using JWT. The JWT secret is stored in a file specified in config/gitlab.yml. By default, the location is in the root of the GitLab Rails app in a file called .gitlab_kas_secret.

GitLab agent information

Called from GitLab agent server (kas) to retrieve agent information for the given agent token. This returns the Gitaly connection information for the agent’s project in order for kas to fetch and update the agent’s configuration.

GET /internal/kubernetes/agent_info

Example Request:

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/agent_info"

GitLab agent project information

Called from GitLab agent server (kas) to retrieve project information for the given agent token. This returns the Gitaly connection for the requested project. GitLab kas uses this to configure the agent to fetch Kubernetes resources from the project repository to sync.

Only public projects are supported. For private projects, the ability for the agent to be authorized is not yet implemented.

GET /internal/kubernetes/project_info

Example Request:

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/project_info?id=7"

GitLab agent usage metrics

Called from GitLab agent server (kas) to increase the usage metric counters.

POST /internal/kubernetes/usage_metrics

Example Request:

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" --header "Content-Type: application/json" \
     --data '{"counters": {"gitops_sync":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

Create Starboard vulnerability

Called from the GitLab agent server (kas) to create a security vulnerability from a Starboard vulnerability report. This request is idempotent. Multiple requests with the same data create a single vulnerability. The response contains the UUID of the created vulnerability finding.

PUT internal/kubernetes/modules/starboard_vulnerability

Example Request:

curl --request PUT --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability" \
     --data '{
  "vulnerability": {
    "name": "CVE-123-4567 in libc",
    "severity": "high",
    "confidence": "unknown",
    "location": {
      "kubernetes_resource": {
        "namespace": "production",
        "kind": "deployment",
        "name": "nginx",
        "container": "nginx"
      }
    },
    "identifiers": [
      {
        "type": "cve",
        "name": "CVE-123-4567",
        "value": "CVE-123-4567"
      }
    ]
  },
  "scanner": {
    "id": "starboard_trivy",
    "name": "Trivy (via Starboard Operator)",
    "vendor": "GitLab"
  }
}'

Example response:

{
  "uuid": "4773b2ee-5ba5-5e9f-b48c-5f7a17f0faac"
}

Resolve Starboard vulnerabilities

Called from the GitLab agent server (kas) to resolve Starboard security vulnerabilities. Accepts a list of finding UUIDs and marks all Starboard vulnerabilities not identified by the list as resolved.

POST internal/kubernetes/modules/starboard_vulnerability/scan_result

Example Request:

curl --request POST --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" --header "Content-Type: application/json" \
     --url "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_result" \
     --data '{ "uuids": ["102e8a0a-fe29-59bd-b46c-57c3e9bc6411", "5eb12985-0ed5-51f4-b545-fd8871dc2870"] }'

Scan Execution Policies

Called from GitLab agent server (kas) to retrieve scan_execution_policies configured for the project belonging to the agent token. GitLab kas uses this to configure the agent to scan images in the Kubernetes cluster based on the policy.

GET /internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies

Example Request:

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/scan_execution_policies"

Example response:

{
  "policies": [
    {
      "name": "Policy",
      "description": "Policy description",
      "enabled": true,
      "yaml": "---\nname: Policy\ndescription: 'Policy description'\nenabled: true\nactions:\n- scan: container_scanning\nrules:\n- type: pipeline\n  branches:\n  - main\n",
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

Policy Configuration

Called from GitLab agent server (kas) to retrieve policies_configuration configured for the project belonging to the agent token. GitLab kas uses this to configure the agent to scan images in the Kubernetes cluster based on the configuration.

GET /internal/kubernetes/modules/starboard_vulnerability/policies_configuration

Example Request:

curl --request GET --header "Gitlab-Kas-Api-Request: <JWT token>" \
     --header "Authorization: Bearer <agent token>" "http://localhost:3000/api/v4/internal/kubernetes/modules/starboard_vulnerability/policies_configuration"

Example response:

{
  "configurations": [
    {
      "cadence": "30 2 * * *",
      "namespaces": [
        "namespace-a",
        "namespace-b"
      ],
      "updated_at": "2022-06-02T05:36:26+00:00"
    }
  ]
}

Subscriptions

The subscriptions endpoint is used by CustomersDot (customers.gitlab.com) to apply subscriptions including trials, and add-on purchases, for personal namespaces or top-level groups within GitLab.com.

Create a subscription

Use a POST command to create a subscription.

POST /namespaces/:id/gitlab_subscription

Example request:

curl --request POST --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?start_date="2020-07-15"&plan="premium"&seats=10"

Example response:

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":10,
    "seats_in_use":1,
    "max_seats_used":0,
    "seats_owed":0
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":null,
    "trial_ends_on":null
  }
}

Update a subscription

Use a PUT command to update an existing subscription.

PUT /namespaces/:id/gitlab_subscription

Example request:

curl --request PUT --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription?max_seats_used=0"

Example response:

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":0,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

Retrieve a subscription

Use a GET command to view an existing subscription.

GET /namespaces/:id/gitlab_subscription

Example request:

curl --header "TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/gitlab_subscription"

Example response:

{
  "plan": {
    "code":"premium",
    "name":"premium",
    "trial":false,
    "auto_renew":null,
    "upgradable":false,
    "exclude_guests":false,
  },
  "usage": {
    "seats_in_subscription":80,
    "seats_in_use":82,
    "max_seats_used":82,
    "seats_owed":2
  },
  "billing": {
    "subscription_start_date":"2020-07-15",
    "subscription_end_date":"2021-07-15",
    "trial_ends_on":null
  }
}

Known consumers

• CustomersDot

Subscription add-on purchases (excluding storage and compute packs)

The subscription add-on purchase endpoint is used by CustomersDot (customers.gitlab.com) to apply subscription add-on purchases like code suggestions for personal namespaces, or top-level groups within GitLab.com. It is not used to apply storage and compute pack purchases.

Create a subscription add-on purchase

Use a POST command to create a subscription add-on purchase.

POST /namespaces/:id/subscription_add_on_purchase/:add_on_name

Example request:

curl --request POST --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=10&expires_on="2024-07-15"&purchase_xid="A-S12345678""

Example response:

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":10,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

Update a subscription add-on purchases

Use a PUT command to update an existing subscription add-on purchase.

PUT /namespaces/:id/subscription_add_on_purchase/:add_on_name

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions?&quantity=15&expires_on="2024-07-15"&purchase_xid="A-S12345678""

Example response:

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

Retrieve a subscription add-on purchases

Use a GET command to view an existing subscription add-on purchase.

GET /namespaces/:id/subscription_add_on_purchase/:add_on_name

Example request:

curl --header "PRIVATE-TOKEN: <admin_access_token>" "https://gitlab.com/api/v4/namespaces/1234/subscription_add_on_purchase/code_suggestions"

Example response:

{
  "namespace_id":1234,
  "namespace_name":"A Namespace Name",
  "add_on":"Code Suggestions",
  "quantity":15,
  "expires_on":"2024-07-15",
  "purchase_xid":"A-S12345678"
}

Known consumers

• CustomersDot

Storage limit exclusions

The namespace storage limit exclusion endpoints manage storage limit exclusions on top-level namespaces on GitLab.com. These endpoints can only be consumed in the Admin Area of GitLab.com.

Retrieve storage limit exclusions

Use a GET request to retrieve all Namespaces::Storage::LimitExclusion records.

GET /namespaces/storage/limit_exclusions

Example request:

curl --request GET \
  --url "https://gitlab.com/v4/namespaces/storage/limit_exclusions" \
  --header 'PRIVATE-TOKEN: <admin access token>'

Example response:

[
    {
      "id": 1,
      "namespace_id": 1234,
      "namespace_name": "A Namespace Name",
      "reason": "a reason to exclude the Namespace"
    },
    {
      "id": 2,
      "namespace_id": 4321,
      "namespace_name": "Another Namespace Name",
      "reason": "another reason to exclude the Namespace"
    },
]

Create a storage limit exclusion

Use a POST request to create an Namespaces::Storage::LimitExclusion.

POST /namespaces/:id/storage/limit_exclusion

Example request:

curl --request POST \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "reason": "a reason to exclude the Namespace"
  }'

Example response:

{
  "id": 1,
  "namespace_id": 1234,
  "namespace_name": "A Namespace Name",
  "reason": "a reason to exclude the Namespace"
}

Delete a storage limit exclusion

Use a DELETE request to delete a Namespaces::Storage::LimitExclusion for a namespace.

DELETE /namespaces/:id/storage/limit_exclusion

Example request:

curl --request DELETE \
  --url "https://gitlab.com/v4/namespaces/123/storage/limit_exclusion" \
  --header 'PRIVATE-TOKEN: <admin access token>'

Example response:

204

Known consumers

• GitLab.com Admin Area

Compute quota provisioning

The compute quota endpoints are used by CustomersDot (customers.gitlab.com) to apply additional packs of compute minutes, for personal namespaces or top-level groups in GitLab.com.

Create an additional pack

Use a POST command to create additional packs.

POST /namespaces/:id/minutes

Example request:

curl --request POST \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes" \
  --header 'Content-Type: application/json' \
  --header 'PRIVATE-TOKEN: <admin access token>' \
  --data '{
    "packs": [
      {
        "number_of_minutes": 10000,
        "expires_at": "2022-01-01",
        "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
      }
    ]
  }'

Example response:

[
  {
    "namespace_id": 123,
    "expires_at": "2022-01-01",
    "number_of_minutes": 10000,
    "purchase_xid": "46952fe69bebc1a4de10b2b4ff439d0c"
  }
]

Move additional packs

Use a PATCH command to move additional packs from one namespace to another.

PATCH /namespaces/:id/minutes/move/:target_id

Example request:

curl --request PATCH \
  --url "http://localhost:3000/api/v4/namespaces/123/minutes/move/321" \
  --header 'PRIVATE-TOKEN: <admin access token>'

Example response:

{
  "message": "202 Accepted"
}

Known consumers

• CustomersDot

Upcoming reconciliations

The upcoming_reconciliations endpoint is used by CustomersDot (customers.gitlab.com) to update upcoming reconciliations for namespaces.

Update upcoming_reconciliations

Use a PUT command to update upcoming_reconciliations.

PUT /internal/upcoming_reconciliations

Each array element contains:

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <admin_access_token>" --header "Content-Type: application/json" \
     --data '{"upcoming_reconciliations": [{"namespace_id": 127, "next_reconciliation_date": "13 Jun 2021", "display_alert_from": "06 Jun 2021"}, {"namespace_id": 129, "next_reconciliation_date": "12 Jun 2021", "display_alert_from": "05 Jun 2021"}]}' \
     "https://gitlab.com/api/v4/internal/upcoming_reconciliations"

Example response:

200

Delete an upcoming_reconciliation

Use a DELETE command to delete an upcoming_reconciliation.

DELETE /internal/upcoming_reconciliations

Example request:

curl --request DELETE \
  --url "http://localhost:3000/api/v4/internal/upcoming_reconciliations?namespace_id=22" \
  --header 'PRIVATE-TOKEN: <admin_access_token>'

Example response:

204

Known consumers

• CustomersDot

Group SCIM API

The group SCIM API implements the RFC7644 protocol. As this API is for system use for SCIM provider integration, it is subject to change without notice.

To use this API, enable Group SSO for the group. This API is only in use where SCIM for Group SSO is enabled. It’s a prerequisite to the creation of SCIM identities.

This API is different to the main SCIM API and the instance SCIM API.

Get a list of SCIM provisioned users

This endpoint is used as part of the SCIM syncing mechanism. It only returns a single user based on a unique ID which should match the extern_uid of the user.

GET /api/scim/v2/groups/:group_path/Users

Parameters:

Example request:

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

Get a single SCIM provisioned user

GET /api/scim/v2/groups/:group_path/Users/:id

Parameters:

Example request:

curl "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

Create a SCIM provisioned user

POST /api/scim/v2/groups/:group_path/Users/

Parameters:

Example request:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/groups/test_group/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

Returns a 201 status code if successful.

Update a single SCIM provisioned user

Fields that can be updated are:

PATCH /api/scim/v2/groups/:group_path/Users/:id

Parameters:

Example request:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"name.formatted","value":"New Name"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Returns an empty response with a 204 status code if successful.

Remove a single SCIM provisioned user

Removes the user’s SSO identity and group membership.

DELETE /api/scim/v2/groups/:group_path/Users/:id

Parameters:

Example request:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Returns an empty response with a 204 status code if successful.

Instance SCIM API

The Instance SCIM API implements the RFC7644 protocol. As this API is for system use for SCIM provider integration, it is subject to change without notice.

To use this API, enable SAML SSO for the instance.

This API is different to the main SCIM API and the group SCIM API.

Get a list of SCIM provisioned users

This endpoint is used as part of the SCIM syncing mechanism. It only returns a single user based on a unique ID which should match the extern_uid of the user.

GET /api/scim/v2/application/Users

Parameters:

Example request:

curl "https://gitlab.example.com/api/scim/v2/application/Users?filter=id%20eq%20%220b1d561c-21ff-4092-beab-8154b17f82f2%22" \
     --header "Authorization: Bearer <your_scim_token>" \
     --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 20,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
      "active": true,
      "name.formatted": "Test User",
      "userName": "username",
      "meta": { "resourceType":"User" },
      "emails": [
        {
          "type": "work",
          "value": "name@example.com",
          "primary": true
        }
      ]
    }
  ]
}

Get a single SCIM provisioned user

GET /api/scim/v2/application/Users/:id

Parameters:

Example request:

curl "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

Create a SCIM provisioned user

POST /api/scim/v2/application/Users

Parameters:

Example request:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Users" \
     --data '{"externalId":"test_uid","active":null,"userName":"username","emails":[{"primary":true,"type":"work","value":"name@example.com"}],"name":{"formatted":"Test User","familyName":"User","givenName":"Test"},"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],"meta":{"resourceType":"User"}}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "0b1d561c-21ff-4092-beab-8154b17f82f2",
  "active": true,
  "name.formatted": "Test User",
  "userName": "username",
  "meta": { "resourceType":"User" },
  "emails": [
    {
      "type": "work",
      "value": "name@example.com",
      "primary": true
    }
  ]
}

Returns a 201 status code if successful.

Update a single SCIM provisioned user

Fields that can be updated are:

PATCH /api/scim/v2/application/Users/:id

Parameters:

Example request:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --data '{ "Operations": [{"op":"Update","path":"active","value":"false"}] }' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Returns an empty response with a 204 status code if successful.

Remove a single SCIM provisioned user

The user is placed in an ldap_blocked status and signed out. This means the user cannot sign in or push or pull code.

DELETE /api/scim/v2/application/Users/:id

Parameters:

Example request:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Returns an empty response with a 204 status code if successful.

Available filters

They match an expression as specified in the RFC7644 filtering section.

Example:

id eq a-b-c-d

Available operations

They perform an operation as specified in the RFC7644 update section.

Example:

{ "op": "Add", "path": "name.formatted", "value": "New Name" }