SCIM API

The SCIM API implements the the RFC7644 protocol.

Note: Group SSO must be enabled for the group. For more information, see SCIM setup documentation.

Get a list of SAML users

Note: This endpoint is used as part of the SCIM syncing mechanism and 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:

AttributeTypeRequiredDescription
filterstringnoA filter expression.
group_pathstringyesFull path to the group.
startIndexintegernoThe 1-based index indicating where to start returning results from. A value of less than one will be interpreted as 1.
countintegernoDesired maximum number of query results.
Note: 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://example.gitlab.com/api/scim/v2/groups/test_group/Users?filter=id%20eq%20"0b1d561c-21ff-4092-beab-8154b17f82f2"' --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 SAML user

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

Parameters:

AttributeTypeRequiredDescription
idstringyesExternal UID of the user.
group_pathstringyesFull path to the group.

Example request:

curl 'https://example.gitlab.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 SAML user

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

Parameters:

AttributeTypeRequiredDescription
externalIdstringyesExternal UID of the user.
userNamestringyesUsername of the user.
emailsJSON stringyesWork email.
nameJSON stringyesName of the user.
metastringnoResource type (`User’).

Example request:

curl --verbose --request POST 'https://example.gitlab.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 SAML user

Fields that can be updated are:

SCIM/IdP fieldGitLab field
id/externalIdextern_uid
name.formattedname
emails[type eq “work”].valueemail
activeIdentity removal if active = false
userNameusername
PATCH /api/scim/v2/groups/:group_path/Users/:id

Parameters:

AttributeTypeRequiredDescription
idstringyesExternal UID of the user.
group_pathstringyesFull path to the group.
OperationsJSON stringyesAn operations expression.

Example request:

curl --verbose --request PATCH 'https://example.gitlab.com/api/scim/v2/groups/test_group/Users/f0b1d561c-21ff-4092-beab-8154b17f82f2' --data '{ "Operations": [{"op":"Add","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 SAML user

Removes the user’s SSO identity and group membership.

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

Parameters:

AttributeTypeRequiredDescription
idstringyesExternal UID of the user.
group_pathstringyesFull path to the group.

Example request:

curl --verbose --request DELETE 'https://example.gitlab.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.

Available filters

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

FilterDescription
eqThe attribute matches exactly the specified value.

Example:

id eq a-b-c-d

Available operations

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

OperatorDescription
ReplaceThe attribute’s value is updated.
AddThe attribute has a new value.

Example:

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