SCIM API
Offering: GitLab.com
- Introduced in GitLab 15.5.
The GitLab SCIM API manages SCIM identities within groups and provides the /groups/:groups_id/scim/identities
and /groups/:groups_id/scim/:uid
endpoints. The base URL is <http|https>://<GitLab host>/api/v4
.
To use this API, Group SSO must be enabled 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 internal group SCIM API and the instance SCIM API:
- This API:
- Does not implement the RFC7644 protocol.
- Gets, checks, updates, and deletes SCIM identities within groups.
- The internal group and instance SCIM APIs:
- Are for system use for SCIM provider integration.
- Implement the RFC7644 protocol.
- Get a list of SCIM provisioned users for the group or instance.
- Create, delete and update SCIM provisioned users for the group or instance.
Get SCIM identities for a group
- Introduced in GitLab 15.5.
GET /groups/:id/scim/identities
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | Yes | The ID or URL-encoded path of the group |
If successful, returns 200
and the following
response attributes:
Attribute | Type | Description |
---|---|---|
extern_uid
| string | External UID for the user |
user_id
| integer | ID for the user |
active
| boolean | Status of the identity |
Example response:
[
{
"extern_uid": "be20d8dcc028677c931e04f387",
"user_id": 48,
"active": true
}
]
Example request:
curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/identities" \
--header "PRIVATE-TOKEN: <PRIVATE-TOKEN>"
Get a single SCIM identity
- Introduced in GitLab 16.1.
GET /groups/:id/scim/:uid
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID or URL-encoded path of the group |
uid
| string | yes | External UID of the user. |
Example request:
curl --location --request GET "https://gitlab.example.com/api/v4/groups/33/scim/be20d8dcc028677c931e04f387" --header "PRIVATE-TOKEN: <PRIVATE TOKEN>"
Example response:
{
"extern_uid": "be20d8dcc028677c931e04f387",
"user_id": 48,
"active": true
}
Update extern_uid
field for a SCIM identity
- Introduced in GitLab 15.5.
Fields that can be updated are:
SCIM/IdP field | GitLab field |
---|---|
id/externalId
| extern_uid
|
PATCH /groups/:groups_id/scim/:uid
Parameters:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the group |
uid
| string | yes | External UID of the user. |
Example request:
curl --location --request PATCH "https://gitlab.example.com/api/v4/groups/33/scim/be20d8dcc028677c931e04f387" \
--header "PRIVATE-TOKEN: <PRIVATE TOKEN>" \
--form "extern_uid=yrnZW46BrtBFqM7xDzE7dddd"
Delete a single SCIM identity
- Introduced in GitLab 16.5.
DELETE /groups/:id/scim/:uid
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer | yes | The ID or URL-encoded path of the group. |
uid
| string | yes | External UID of the user. |
Example request:
curl --request DELETE --header "Content-Type: application/json" --header "Authorization: Bearer <your_access_token>" "https://gitlab.example.com/api/v4/groups/33/scim/yrnZW46BrtBFqM7xDzE7dddd"
Example response:
{
"message" : "204 No Content"
}