SCIM API Reference

This document details all the operations available through the SCIM (System for Cross-domain Identity Management) API for managing users and groups.

Authentication

All API requests require authentication using a SCIM token associated with the specified account.

Example Header:

Authorization: Bearer {your_token_here}
Content-Type: application/json

Users API

List all users

Retrieves all users for the specified account.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Users

Query Parameters:

filter (optional): Filter string in format field operator "value". Available operators: eq, ne, co, sw, ew

Example Request:

GET /api/v1/accounts/123456/scim/v2/Users

Example Request with Filter:

GET /api/v1/accounts/123456/scim/v2/Users?filter=userName eq "[email protected]"

Example Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
      "userName": "[email protected]",
      "name": {
        "givenName": "Example",
        "familyName": "User"
      },
      "emails": [
        {
          "value": "[email protected]",
          "type": "work",
          "primary": true
        }
      ],
      "active": true
    }
  ]
}

Get a specific user

Retrieves a specific user by ID.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Users/{user_id}

Example Request:

GET /api/v1/accounts/123456/scim/v2/Users/a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
  "userName": "[email protected]",
  "name": {
    "givenName": "Example",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true
}

Create a user

Creates a new user in the specified account.

Note: The expectation is that the user name will be the primary email of the user for the CG account.

Endpoint: POST /api/v1/accounts/{account_id}/scim/v2/Users

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "[email protected]",
  "name": {
    "givenName": "New",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "externalId": "employee-12345"
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9",
  "userName": "[email protected]",
  "name": {
    "givenName": "New",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "externalId": "employee-12345"
}

Update a user (PUT)

Updates an existing user by replacing all attributes.

Endpoint: PUT /api/v1/accounts/{account_id}/scim/v2/Users/{user_id}

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9",
  "userName": "[email protected]",
  "name": {
    "givenName": "Updated",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "externalId": "employee-12345-updated"
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9",
  "userName": "[email protected]",
  "name": {
    "givenName": "Updated",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "externalId": "employee-12345-updated"
}

Modify a user (PATCH)

Partially updates a user by applying operations.

Note: Primary Email can not be modified.

Endpoint: PATCH /api/v1/accounts/{account_id}/scim/v2/Users/{user_id}

Request Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name.givenName",
      "value": "PatchedName"
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9",
  "userName": "[email protected]",
  "name": {
    "givenName": "PatchedName",
    "familyName": "User"
  },
  "emails": [
    {
      "value": "[email protected]",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "externalId": "employee-12345-updated"
}

Delete a user

Deletes a user.

Endpoint: DELETE /api/v1/accounts/{account_id}/scim/v2/Users/{user_id}

Example Request:

DELETE /api/v1/accounts/123456/scim/v2/Users/b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9

Example Response:

Status: 204 No Content

Groups API

List all groups

Retrieves all groups for the specified account.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Groups

Query Parameters:

filter (optional): Filter string in format field operator "value". Available operators: eq, ne, co, sw, ew

Example Request:

GET /api/v1/accounts/123456/scim/v2/Groups

Example Request with Filter:

GET /api/v1/accounts/123456/scim/v2/Groups?filter=displayName eq "Test Group"

Example Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "id": "c34d56e7-8f9a-0b1c-d2e3-f4g5h6i7j8k9",
      "displayName": "Test Group",
      "members": [
        {
          "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
          "display": "Example User"
        }
      ]
    }
  ]
}

Get a specific group

Retrieves a specific group by ID.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Groups/{group_id}

Example Request:

GET /api/v1/accounts/123456/scim/v2/Groups/c34d56e7-8f9a-0b1c-d2e3-f4g5h6i7j8k9

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "c34d56e7-8f9a-0b1c-d2e3-f4g5h6i7j8k9",
  "displayName": "Test Group",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
      "display": "Example User"
    }
  ]
}

Create a group

Creates a new group in the specified account.

Endpoint: POST /api/v1/accounts/{account_id}/scim/v2/Groups

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Test Group",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8"
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Test Group",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
      "display": "Example User"
    }
  ]
}

Update a group (PUT)

Updates an existing group by replacing all attributes.

Endpoint: PUT /api/v1/accounts/{account_id}/scim/v2/Groups/{group_id}

Request Body:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Updated Test Group",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8"
    },
    {
      "value": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9"
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Updated Test Group",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
      "display": "Example User"
    },
    {
      "value": "b23c45d6-7e89-0f1a-b2c3-d4e5f6g7h8i9",
      "display": "New User"
    }
  ]
}

Modify a group (PATCH)

Partially updates a group by applying operations.

Endpoint: PATCH /api/v1/accounts/{account_id}/scim/v2/Groups/{group_id}

Request Body (Updating Display Name):

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "displayName",
      "value": "Patched Group Name"
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Patched Group Name",
  "members": []
}

Request Body (Adding Members):

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
        }
      ]
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Patched Group Name",
  "members": [
    {
      "value": "a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8",
      "$ref": "<reference_link>"
    },
  ]
}

Request Body (Removing Members):

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"a12b34c5-6d78-9e0f-g1h2-i3j4k5l6m7n8\"]"
    }
  ]
}

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0",
  "displayName": "Patched Group Name",
  "members": []
}

Delete a group

Deletes a group.

Endpoint: DELETE /api/v1/accounts/{account_id}/scim/v2/Groups/{group_id}

Example Request:

DELETE /api/v1/accounts/123456/scim/v2/Groups/d45e67f8-9a0b-1c2d-e3f4-g5h6i7j8k9l0

Example Response:

Status: 204 No Content

Service Provider Config API

Get Service Provider Config

Retrieves information about the capabilities of the SCIM service provider.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/ServiceProviderConfig

Example Request:

GET /api/v1/accounts/123456/scim/v2/ServiceProviderConfig

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "documentationUri": "https://example.com/docs/scim",
  "patch": {
    "supported": true
  },
  "bulk": {
    "supported": false,
    "maxOperations": 0,
    "maxPayloadSize": 0
  },
  "filter": {
    "supported": true,
    "maxResults": 200
  },
  "changePassword": {
    "supported": false
  },
  "sort": {
    "supported": false
  },
  "etag": {
    "supported": false
  },
  "authenticationSchemes": [
    {
      "name": "OAuth Bearer Token",
      "description": "Authentication scheme using the OAuth Bearer Token Standard",
      "specUri": "https://tools.ietf.org/html/rfc6750",
      "type": "oauthbearertoken",
      "primary": true
    }
  ]
}

Resource Types API

List all resource types

Retrieves information about all resource types supported by the SCIM service provider.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/ResourceTypes

Example Request:

GET /api/v1/accounts/123456/scim/v2/ResourceTypes

Example Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [],
      "meta": {
        "location": "/ResourceTypes/User",
        "resourceType": "ResourceType"
      }
    },
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "Group",
      "name": "Group",
      "endpoint": "/Groups",
      "description": "Group",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "schemaExtensions": [],
      "meta": {
        "location": "/ResourceTypes/Group",
        "resourceType": "ResourceType"
      }
    }
  ]
}

Get a specific resource type

Retrieves information about a specific resource type.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/ResourceTypes/{resource_type}

Example Request:

GET /api/v1/accounts/123456/scim/v2/ResourceTypes/User

Example Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
  "id": "User",
  "name": "User",
  "endpoint": "/Users",
  "description": "User Account",
  "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
  "schemaExtensions": [],
  "meta": {
    "location": "/ResourceTypes/User",
    "resourceType": "ResourceType"
  }
}

Schemas API

List all schemas

Retrieves all schemas supported by the SCIM service provider.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Schemas

Example Request:

GET /api/v1/accounts/123456/scim/v2/Schemas

Example Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "Resources": [
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "User Schema",
      "attributes": [
        // Attributes omitted for brevity
      ],
      "meta": {
        "resourceType": "Schema",
        "location": "/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
      }
    },
    {
      "id": "urn:ietf:params:scim:schemas:core:2.0:Group",
      "name": "Group",
      "description": "Group Schema",
      "attributes": [
        // Attributes omitted for brevity
      ],
      "meta": {
        "resourceType": "Schema",
        "location": "/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
      }
    }
  ]
}

Get a specific schema

Retrieves a specific schema by its URN.

Endpoint: GET /api/v1/accounts/{account_id}/scim/v2/Schemas/{schema_urn}

Example Request:

GET /api/v1/accounts/123456/scim/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User

Example Response:

{
  "id": "urn:ietf:params:scim:schemas:core:2.0:User",
  "name": "User",
  "description": "User Schema",
  "attributes": [
    {
      "name": "userName",
      "type": "string",
      "multiValued": false,
      "description": "Unique identifier for the User",
      "required": true,
      "caseExact": false,
      "mutability": "readWrite",
      "returned": "default",
      "uniqueness": "server"
    },
    // Other attributes omitted for brevity
  ],
  "meta": {
    "resourceType": "Schema",
    "location": "/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
  }
}

Filter Limitations

Supported Operations

The SCIM API supports the following filter operations:

eq - Equal to
ne - Not equal to
co - Contains
sw - Starts with
ew - Ends with

User Filterable Fields

The following fields can be filtered for User resources:

username (maps to primary email)
workemail (maps to primary email)
mail (maps to primary email)
name.givenname (maps to first_name)
givenname (maps to first_name)
name.familyname (maps to last_name)
familyname (maps to last_name)
externalid (maps to externalId)

Note: Primary Email once set can not be changed.

Group Filterable Fields

The following fields can be filtered for Group resources:

displayname

Additional Limitations

All string comparisons are case-insensitive
Empty string values are handled specially:
- For eq operations: Matches both empty strings and NULL values
- For ne operations: Matches neither empty strings nor NULL values
- Other operations require non-empty values
Filters are applied with AND logic - all conditions must be met
Complex filters (with OR conditions or nested expressions) are not supported
No support for filtering on array fields (like members in groups)

Authentication​

Users API​

List all users​

Get a specific user​

Create a user​

Update a user (PUT)​

Modify a user (PATCH)​

Delete a user​

Groups API​

List all groups​

Get a specific group​

Create a group​

Update a group (PUT)​

Modify a group (PATCH)​

Delete a group​

Service Provider Config API​

Get Service Provider Config​

Resource Types API​

List all resource types​

Get a specific resource type​

Schemas API​

List all schemas​

Get a specific schema​

Filter Limitations​

Supported Operations​

User Filterable Fields​

Group Filterable Fields​

Additional Limitations​

Authentication

Users API

List all users

Get a specific user

Create a user

Update a user (PUT)

Modify a user (PATCH)

Delete a user

Groups API

List all groups

Get a specific group

Create a group

Update a group (PUT)

Modify a group (PATCH)

Delete a group

Service Provider Config API

Get Service Provider Config

Resource Types API

List all resource types

Get a specific resource type

Schemas API

List all schemas

Get a specific schema

Filter Limitations

Supported Operations

User Filterable Fields

Group Filterable Fields

Additional Limitations