Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://docs.gitlab.com/development/internal_api/ below:

Internal API | GitLab Docs

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.

For information on the GitLab Subscriptions internal API, see the dedicated page.

API endpoints should be externally accessible by default, with proper authentication and authorization. Before adding a new internal endpoint, consider if the API would benefit 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.

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.

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.

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": []
}

• Gitaly
• GitLab Shell

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
}

• GitLab Shell

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

• GitLab Shell

This endpoint is called by the GitLab Shell to get the namespace that has a particular CA SSH certificate configured. It also accepts user_identifier to return a GitLab user for specified identifier.

GET /internal/authorized_certs

Example request:

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

Example response:

{
  "success": true,
  "namespace": "gitlab-org",
  "username": "root"
}

• GitLab Shell

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

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

• GitLab Shell

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

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
}

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

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

• GitLab Shell

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

• GitLab Shell

This endpoint is called by the error tracking Go REST API application to authenticate a project.

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:

• OpsTrace

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
}

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
}

The following endpoints are used by the GitLab agent server for Kubernetes (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.

Called from the GitLab agent server for Kubernetes (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"

Called from the GitLab agent server for Kubernetes (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"

Called from the GitLab agent server for Kubernetes (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": {"k8s_api_proxy_request":1}}' "http://localhost:3000/api/v4/internal/kubernetes/usage_metrics"

Called from the GitLab agent server for Kubernetes (kas) to track events.

POST /internal/kubernetes/agent_events

Example Request:

curl --request POST \
  --url "http://localhost:3000/api/v4/internal/kubernetes/agent_events" \
  --header "Gitlab-Kas-Api-Request: <JWT token>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": {
      "k8s_api_proxy_requests_unique_users_via_ci_access": [
        {
          "user_id": 1,
          "project_id": 1
        }
      ]
    }
  }'

Called from the GitLab agent server for Kubernetes (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"
}

Called from the GitLab agent server for Kubernetes (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"] }'

Called from GitLab agent server for Kubernetes (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"
    }
  ]
}

Called from GitLab agent server for Kubernetes (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"
    }
  ]
}

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.

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"
    },
]

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

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:

• GitLab.com Admin area

• Tier: Premium, Ultimate
• Offering: GitLab.com

The group SCIM API partially implements the RFC7644 protocol. This API provides the /groups/:group_path/Users and /groups/:group_path/Users/:id endpoints. The base URL is <http|https>://<GitLab host>/api/scim/v2. Because 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 group SCIM API:

• Is for system use for SCIM provider integration.
• Implements the RFC7644 protocol.
• Gets a list of SCIM provisioned users for the group.
• Creates, deletes and updates SCIM provisioned users for the group.

The instance SCIM API does the same for instances.

This group SCIM API is different to the SCIM API. The SCIM API:

• Is not an internal API.
• Does not implement the RFC7644 protocol.
• Gets, checks, updates, and deletes SCIM identities in groups.

This API does not require the Gitlab-Shell-Api-Request header.

This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used.

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

Parameters:

Pagination follows the SCIM spec rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request.

Example request filtering on a specific identifier:

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

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.

After you create a group SCIM identity for a user, you can see that SCIM identity in the Admin area.

Fields that can be updated are:

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

Parameters:

Example request to update the user’s id:

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

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

Example request to set the user’s active state:

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

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

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.

• Tier: Premium, Ultimate
• Offering: GitLab Self-Managed

History

• Group sync support added in GitLab 18.0.

The instance SCIM API partially implements the RFC7644 protocol. This API provides endpoints for managing users and groups. The base URL is <http|https>://<GitLab host>/api/scim/v2. Because 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 instance SCIM API:

• Is for system use for SCIM provider integration.
• Implements the RFC7644 protocol.
• Gets a list of SCIM provisioned users.
• Creates, deletes, and updates SCIM provisioned users.
• Manages group memberships through SAML group links.

The group SCIM API does the same for groups.

This instance SCIM API is different to the SCIM API. The SCIM API:

• Is not an internal API.
• Does not implement the RFC7644 protocol.
• Gets, checks, updates, and deletes SCIM identities within groups.

This API does not require the Gitlab-Shell-Api-Request header.

Use user endpoints to manage SCIM provisioned users.

This endpoint is used as part of the SCIM syncing mechanism. It returns a list of users depending on the filter used.

GET /api/scim/v2/application/Users

Parameters:

Pagination follows the SCIM spec rather than GitLab pagination as used elsewhere. If records change between requests it is possible for a page to either be missing records that have moved to a different page or repeat records from a previous request.

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

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.

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.

The user is placed in a blocked state 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.

Use group endpoints to automatically synchronize GitLab with the SCIM identity provider.

This API uses SAML group links to connect IdP groups with GitLab groups. Before using these endpoints, you must create the necessary SAML group links for the groups you want to synchronize.

This endpoint returns a list of groups that have SCIM IDs assigned.

GET /api/scim/v2/application/Groups

Parameters:

Pagination follows the SCIM spec, not the GitLab pagination.

Example request:

curl "https://gitlab.example.com/api/scim/v2/application/Groups?filter=displayName%20eq%20%22Developers%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:Group"
      ],
      "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
      "displayName": "Developers",
      "members": [],
      "meta": {
        "resourceType": "Group"
      }
    }
  ]
}

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

Parameters:

Example request:

curl "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

This endpoint associates a SCIM group ID with existing SAML group links that have the same name.

POST /api/scim/v2/application/Groups

Parameters:

Example request:

curl --verbose --request POST "https://gitlab.example.com/api/scim/v2/application/Groups" \
     --data '{"displayName":"Developers","schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example response:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "86e7d437-1a55-4731-b3a3-2867fb4d2a94",
  "displayName": "Developers",
  "members": [],
  "meta": {
    "resourceType": "Group"
  }
}

Returns a 201 status code if successful.

This endpoint does not create GitLab groups. It only associates a SCIM ID with existing SAML group links that have the specified display name.

Updates the members of a SCIM group. Used to add or remove users from GitLab groups associated with the SCIM group.

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

Parameters:

Supported operations:

• add with path members to add members to the group
• remove with path members to remove members from the group

Example request to add a member:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"add","path":"members","value":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Example request to remove a member:

curl --verbose --request PATCH "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations":[{"op":"remove","path":"members","value":[{"value":"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.

Replaces all members of a SCIM group with a new set of members.

PUT /api/scim/v2/application/Groups/:id

Parameters:

Example request:

curl --verbose --request PUT "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --data '{"schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],"displayName":"Developers","members":[{"value":"f0b1d561c-21ff-4092-beab-8154b17f82f2"}]}' \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

Response includes the updated group information.

The PUT operation replaces all group members. Any existing members not included in the request are removed from all GitLab groups associated with this SCIM group.

Removes SCIM management from existing SAML group links by clearing the SCIM group ID. This endpoint also schedules background cleanup of SCIM group membership tracking records.

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

Parameters:

Example request:

curl --verbose --request DELETE "https://gitlab.example.com/api/scim/v2/application/Groups/86e7d437-1a55-4731-b3a3-2867fb4d2a94" \
     --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

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

This endpoint does not delete GitLab groups. It only removes SCIM management from SAML group links with the specified SCIM group ID, allowing identity providers to deprovision unneeded SCIM groups.

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

Example:

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

Example:

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

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4