SCIM API Guide

  • Updated on Oct 30, 2024
  • Published on Mar 30, 2023
  • 6 minute(s) read
  • Gina Magana
 Prev Next

SCIM (System for Cross-domain Identity Management) manages user accounts and access to systems. It automates adding or removing users, making it easier to manage user identities across multiple systems.

Authentication

Authentication for SCIM refers to the process of verifying the identity of a client or user to ensure they are authorized to access and manage user resources via the SCIM API.

Authentication for SCIM relies on using API keys.

To set up an API key for a user:

  1. Navigate to Setup → Users → Profiles.

  2. Select a user and press the Generate API Key button.

Include the API key as a bearer token in the HTTP header:

Authorization: Bearer API_KEY_HERE

Include the customer ID with every SCIM request either as a URL parameter or in a custom HTTP header:

X-customerID: CUSTOMER_ID_HERE

Authentication Errors

  • 401 Unauthorized: The request lacks valid authentication credentials.

  • 403 Forbidden: The authenticated user does not have permission to access the requested resource.

Ensure that all requests include valid API keys and that the associated user has the necessary permissions.

Mapped user fields

The following table maps SCIM attributes to ACE fields.

SCIM Path

ACE Field

username

username

name.givenName

firstName

name.middleName

middleName

name.familyName

lastName

name.formatted

fullName

emails[type=work}.value

email

phoneNumber[type=work}.value

phone and phoneCountryCode

Note: the “tel:”prefix is removed when stored in ACE and added back when returned via GET because of field size limitations.

phoneNumbers[type=mobile].value

phoneCell

phoneNumbers[type=fax].value

phoneFax

userType

userType (ADMIN, USER, CLIENT_ACCESS)

preferredLanguage

language

timezone

timeZone

active

active

roles

roles

Creating users

POST http://localhost:8080/api/scim/users?customerID=CUSTOMER_ID&apiKey=API_KEY
Content-Type: application/json
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "bjensen",
  "name": {
    "formatted": "Ms. Barbara J Jensen, III",
    "familyName": "Jensen",
    "givenName": "Barbara",
    "middleName": "Jane"
  },
  "emails": [
    {
      "value": "bjensen@example.com"
    }
  ],
  "phoneNumbers": [
    {
      "value": "555-555-5555"
    }
  ],
  "userType": "USER",
  "preferredLanguage": "en-US",
  "timezone": "America/Los_Angeles",
  "active": true,
  "roles": [
    {
      "value": "228961"
    }
  ]
}



HTTP/1.1 201 Created
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "106256",
  "meta": {
    "resourceType": "User",
    "created": "2020-07-10T17:09:42.013-07:00",
    "lastModified": "2020-07-10T17:09:42.013-07:00",
    "location": "/api/scim/users/106256",
    "version": "1594426182013"
  },
  "userName": "bjensen",
  "name": {
    "formatted": "Jensen, Barbara ",
    "familyName": "Jensen",
    "givenName": "Barbara",
    "middleName": "Jane"
  },
  "userType": "USER",
  "timezone": "America/Los_Angeles",
  "active": true,
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "tel:+1-555-555-5555",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "228961",
      "display": "Agent",
      "type": "PERMISSION"
    }
  ]
}

Reading users

Reading a single user

GET http://localhost:8080/api/scim/users/106256?customerID=CUSTOMER_ID&apiKey=API_KEY
Content-Type: application/json

HTTP/1.1 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "106256",
  "meta": {
    "resourceType": "User",
    "created": "2020-07-10T17:09:42.013-07:00",
    "lastModified": "2020-07-10T17:09:42.013-07:00",
    "location": "/api/scim/users/106256",
    "version": "1594426182013"
  },
  "userName": "bjensen",
  "name": {
    "formatted": "Jensen, Barbara ",
    "familyName": "Jensen",
    "givenName": "Barbara",
    "middleName": "Jane"
  },
  "userType": "USER",
  "timezone": "America/Los_Angeles",
  "active": true,
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "tel:+1-555-555-5555",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "228961",
      "display": "Agent",
      "type": "PERMISSION"
    }
  ]
}

 Reading all users

GET http://localhost:8080/api/scim/users?customerID=CUSTOMER_ID&apiKey=API_KEY
Content-Type: application/json

HTTP/1.1 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 68,
  "Resources": [
    { /*...*/ },
    { /*...*/ },
      /*...*/
    { /*...*/ }
  ],
  "startIndex": 1,
  "itemsPerPage": 68
}

Filtering

The URL parameter filter takes a filter in standard SCIM syntax to return only a subset of users.

GET http://localhost:8080/api/scim/users?customerID=CUSTOMER_ID&filter=username%20eq%20%22bjensen%22
Authentication: Bearer API_KEY
Content-Type: application/json

HTTP/1.1 200 OK
{
  "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ],
  "totalResults": 1,
  "Resources": [
    { /*...*/ }
  ],
  "startIndex": 1,
  "itemsPerPage": 1
}

Operators supported

The filter URL parameter allows you to retrieve a subset of users based on specific criteria using standard SCIM syntax.

Operator

Description

eq

Equal to

ne

Not equal to

co

contains string

sw

Starts with

ew

Ends with

pr

Present

gt

Greater than

ge

Greater than or equal to

lt

Less than

le

Less than or equal to

See https://www.rfc-editor.org/rfc/rfc7644#section-3.4.2.2 for more information.

Sorting

The sort parameters sortBy and sortOrder let you control the order of the returned users.

GET http://localhost:8080/api/scim/users?customerID=CUSTOMER_ID&sortBy=username&sortOrder=descending
Authentication: Bearer API_KEY
Content-Type: application/json

HTTP/1.1 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 68,
  "Resources": [
    { /*...*/ },
    { /*...*/ },
      /*... sorted resources ...*/
    { /*...*/ }
  ],
  "startIndex": 1,
  "itemsPerPage": 68
}

Paging

Using the URL parameters startIndex and count, you can control how many users ACE will return in a given request.

GET http://localhost:8080/api/scim/users?customerID=CUSTOMER_ID&startIndex=5&count=3
Authentication: Bearer API_KEY
Content-Type: application/json

HTTP/1.1 200 OK
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 68,
  "Resources": [
    { /*...*/ },
    { /*...*/ },
    { /*...*/ }
  ],
  "startIndex": 5,
  "itemsPerPage": 3
}

Updating Users

Updating a user with a PUT replaces all fields with the new values. If a value is not given for a field, it will be cleared and set to NULL in ACE. 

See Mapped user fields for the full list. Patching a user is not supported. 

PUT http://localhost:8080/api/scim/users/106256?customerID=CUSTOMER_ID
Authentication: Bearer API_KEY
Content-Type: application/json

{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ],
  "id": "106256",
  "userName": "bjensenUP",
  "name": {
    "formatted": "Jensen, Barb",
    "familyName": "JensenU",
    "givenName": "BarbaraU",
    "middleName": "JaneU"
  },
  "userType": "ADMIN",
  "timezone": "America/New_York",
  "active": true,
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "tel:+1-555-555-6666",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "228961",
      "display": "Agent",
      "type": "PERMISSION"
    }
  ]
}

HTTP/1.1 200 OK
{
  "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ],
  "id": "106256",
  "meta": {
    "resourceType": "User",
    "created": "2020-07-10T17:09:42.013-07:00",
    "lastModified": "2020-07-12T16:54:29.859-07:00",
    "location": "/api/scim/users/106256",
    "version": "1594598069859"
  },
  "userName": "bjensenUP",
  "name": {
    "formatted": "Jensenu, Barbarau ",
    "familyName": "JensenU",
    "givenName": "BarbaraU",
    "middleName": "JaneU"
  },
  "userType": "ADMIN",
  "timezone": "America/New_York",
  "active": true,
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "phoneNumbers": [
    {
      "value": "tel:+1-555-555-6666",
      "type": "work",
      "primary": true
    }
  ],
  "roles": [
    {
      "value": "228961",
      "display": "Agent",
      "type": "PERMISSION"
    }
  ]
}

Deleting Users

Users are "soft" deleted in ACE by setting their active status to false. You can do this with a PUT with active set to false, or by using a DELETE call as shown here. Once deleted, they may not be updated until it is reactivated via a POST.

DELETE http://localhost:8080/api/scim/users/106256?customerID=CUSTOMER_ID
Authentication: Bearer API_KEY
Content-Type: application/json

HTTP/1.1 204 No Content

Discovery endpoints

These endpoints are currently all authenticated endpoints, meaning you need to pass the customerID and apiKey with the request.

/api/scim/serviceProviderConfig

Describes what operations and authentication schemes are supported for the SCIM service as a whole.

/api/scim/resourceTypes/user

Describes the user resource endpoint and what schema it uses.

/api/scim/resourceTypes

Returns a list response of size one that just contains the above user resourceType.

/api/scim/schemas/urn:ietf:  params:scim:schemas:core:2.0:  User

Describes the user resource schema, and specifies what attributes (nearly all of them) are required.

/api/scim/schemas

Returns a list response of size one that just contains the above user schema.

Unimplemented Features

Sub-attributes

When querying resources, RFC-7643 specifies that you may list the individual fields you want.  That query parameter is not supported.  All fields are always returned for user objects.

Enterprise user extensions

There are no enterprise user extensions.

PATCH

There is no PATCH call for partial updating users.  Instead, use PUT to update the full user object.

Querying with POST

Querying can only be done on GET calls.  Querying with POST is not supported.

Bulk updates

Bulk updates are not supported.

OAuth or basic authentication

Only authentication with an API key is supported at this time. The api key may be used as a bearer token.

Filtering at root level

Querying for groups and users in one request is not supported.

Filtering on an individual item

Querying on an individual user object is not supported.

Groups

Users are not grouped in ACE, so there is no group endpoint implemented.