SCIM

Authentication

Authentication for SCIM relies on using API keys. You can set up an API key for a user under Setup-Users-Profiles.

Select a user, press the Generate API Key button. 

The API key can be provided as an http header as a bearer token as specified by RFC 6750:

Authorization: Bearer API_KEY_HERE

The customer ID also needs to be included with every SCIM request. It can be passed in as a parameter in the URL or in a custom http header:

X - customerID: CUSTOMER_ID_HERE

Mapped user fields

Creating users

POST http://localhost:8080/json/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": "/json/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/json/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": "/json/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/json/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/json/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

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/json/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/json/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/json/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": "/json/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/json/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.

/json/scim/serviceProviderConfig

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

/json/scim/resourceTypes/user

Describes the user resource endpoint and what schema it uses.

/json/scim/resourceTypes

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

/json/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.

/json/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.