SCIM Provisioning API Reference

Base URL

All SCIM API requests use the following base URL format:

https://{your-site-domain}/@api/deki/scim/v2/{serviceId}/

Where {serviceId} is your IdP's authentication service ID (a numeric value ≥ 2; service 1 is the built-in local provider and is not valid for SCIM). For example, if your Okta SSO connection is service 4, the base URL is:

https://your-site.example.com/@api/deki/scim/v2/4/

Authentication methods

The SCIM API supports two authentication methods:

Test the connection

To verify SCIM is enabled and your credentials are valid, send a GET request to the ServiceProviderConfig endpoint:

GET https://your-site.example.com/@api/deki/scim/v2/{serviceId}/ServiceProviderConfig
Authorization: Basic <base64(key:secret)>

A 200 OK response confirms the connection is working. A 403 Forbidden means SCIM is not enabled on the site or the credentials are invalid.

knowledgeBaseRole attribute (Detail)

The knowledgeBaseRole attribute is a NICE KM extension — a single string naming the role to assign to the user. It is not a multi-valued array.

Available role values:

Behavior:

• NICE KM supports exactly one role per user. The value is a single string, not an array.
• If knowledgeBaseRole is absent or empty, the user defaults to Viewer.
• Role names are matched case-insensitively (e.g. "viewer" resolves to Viewer).
• If the role name does not match any available role, the request is rejected with 400 invalidValue and a detail of role '<name>' does not exist. Validation applies on both create (POST) and update (PATCH/PUT).

Example: Create a user with a role

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jdoe",
  "name": { "givenName": "John", "familyName": "Doe" },
  "emails": [{ "value": "jdoe@example.com", "type": "work", "primary": true }],
  "knowledgeBaseRole": "Contributor",
  "active": true
}

Example: Role in GET response (the role name is normalized to its canonical casing)

"knowledgeBaseRole": "Contributor"

Create user

POST /Users
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "jdoe",
  "externalId": "jdoe-okta-id",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [{ "value": "jdoe@example.com", "type": "work", "primary": true }],
  "knowledgeBaseRole": "Viewer",
  "seated": false,
  "active": true
}

Returns 201 Created with the full User resource including the server-assigned id.

Get user

GET /Users/{id}

Returns 200 OK with the full User resource.

Example response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6",
  "userName": "jdoe",
  "externalId": "jdoe-okta-id",
  "active": true,
  "name": {
    "givenName": "John",
    "familyName": "Doe",
    "formatted": "John Doe"
  },
  "emails": [{ "value": "jdoe@example.com", "type": "work", "primary": true }],
  "knowledgeBaseRole": "Viewer",
  "seated": false,
  "meta": {
    "resourceType": "User",
    "created": "2026-04-28T12:00:00Z",
    "location": "https://your-site.example.com/@api/deki/scim/v2/4/Users/a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6"
  }
}

List / search users

GET /Users?filter=userName eq "jdoe"&startIndex=1&count=10

Returns 200 OK with a ListResponse containing matching users. See Filter, sort, and paginate for details.

Update user (PATCH)

PATCH /Users/{id}
Content-Type: application/scim+json

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

Returns 200 OK with the updated resource.

Replace user (PUT)

PUT /Users/{id}
Content-Type: application/scim+json

Deactivate user (DELETE)

DELETE /Users/{id}

Returns 204 No Content.

Create group

POST /Groups
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName": "Engineering",
  "members": [
    { "value": "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6" }
  ]
}

Returns 201 Created. Group names must be unique; a duplicate returns 409 Conflict.

Add / remove group members (PATCH)

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "user-guid-here" }]
    }
  ]
}

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"user-guid-here\"]"
    }
  ]
}

Delete group

DELETE /Groups/{id}

Group deletion is a hard delete. The group is permanently removed.

Filter operators

Logical operators: and, or, not

Complex filter: emails[type eq "work" and value co "@example.com"]

Server-side filtering (Users)

For performance, the following User attributes are filtered at the database level:

• userName
• externalId
• active
• seated

Filters on other attributes are evaluated in memory after retrieval.

Sortable fields (Users)

id, userName, externalId, active, emails

GET /Users?sortBy=userName&sortOrder=descending

Pagination

Response envelope:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "startIndex": 1,
  "itemsPerPage": 10,
  "Resources": [ ... ]
}

Okta

See User and group provisioning with Okta for step-by-step Okta configuration instructions.

PingFederate

1. In PingFederate, configure an Outbound Provisioning connection.
2. Set the SCIM Base URL to https://{your-site-domain}/@api/deki/scim/v2/{serviceId}/
3. Configure authentication using a Bearer Token (JWT) or HTTP Basic with your Server API Token.
4. In the Attribute Mapping, map the role to the knowledgeBaseRole string attribute (e.g. via a literal expression such as "Viewer" or a source attribute). A bare roles array is not read.
5. Test the connection and trigger an initial provisioning sync.

Microsoft Entra ID (Azure AD)

1. In the Azure portal, go to Enterprise Applications > your application > Provisioning.
2. Set Provisioning Mode to Automatic.
3. Enter the Tenant URL: https://{your-site-domain}/@api/deki/scim/v2/{serviceId}/
4. Enter the Secret Token: your Server API Token key and secret in key:secret format (Base64-encoded) or as a Bearer JWT.
5. Click Test Connection to verify.
6. Configure attribute mappings. Map a source attribute or constant to the knowledgeBaseRole string to assign user roles.
7. You may omit meta and meta.location — Entra's default meta block (resourceType only) is accepted.
8. Enable provisioning and assign users/groups.

Other IdPs

For any SCIM 2.0-compliant identity provider:

1. Set the SCIM base URL: https://{your-site-domain}/@api/deki/scim/v2/{serviceId}/
2. Configure authentication (HTTP Basic or Bearer Token)
3. Use the /Schemas endpoint for automatic attribute discovery
4. Map attributes according to the User Schema Reference above

Known limitations

• One email per user — Only a single email address is supported per User resource.
• Soft delete only — User DELETE sets active: false. Users are never hard-deleted via SCIM.
• One role per user — The role is the single knowledgeBaseRole string. Multi-valued roles arrays are not supported.
• No Bulk operations — The /Bulk endpoint is not supported.
• No ETags — Optimistic concurrency via ETags is not supported.
• Group role is read-only — The role attribute on Groups is set in admin, not through SCIM.
• Resource IDs must be unique — IDs are globally unique GUIDs across all resource types.
• Seated defaults to false — New users are unseated by default. Setting seated: true when all seats are taken returns 409 Conflict.
• No rate limiting at API level — Rate limiting is governed by the API Gateway configuration.

FAQs

Does SCIM handle sign-in?
No. SCIM handles provisioning (creating and managing user accounts). Use SAML or OIDC for authentication (signing in). SCIM and SSO work together: SSO handles how users log in, and SCIM handles which users exist and what access they have.

Can I use SCIM without SSO?
No. SCIM requires an Identity Provider service with an authentication service ID. SSO must be configured before SCIM can be enabled.

How do I find my authentication service ID?
Check your authentication services in the admin panel, or contact the NICE KM Support team. The service ID is the numeric identifier in the SCIM base URL.

What happens to existing users when I enable SCIM?
Existing users are not affected. Use the Import feature in your identity provider to link existing users to their IdP identities.

Can I call the SCIM API directly without an identity provider?
Yes. The SCIM API is a standard REST API. You can call it directly using a Server API Token for authentication. This is useful for custom integrations or scripted user management.

How often does my identity provider sync?
This depends on your IdP configuration. Okta typically syncs every 40 minutes for incremental changes. Microsoft Entra ID syncs approximately every 40 minutes. [VERIFY: confirm current Entra ID provisioning sync interval against Microsoft's documentation] Consult your IdP's documentation for details.

What if a user exists in NICE Knowledge Management but not in my IdP?
SCIM does not delete users that are not in your IdP. Users must be explicitly deactivated or deleted through SCIM operations. Unmanaged users continue to exist in NICE Knowledge Management.

RFC references

• RFC 7642 — SCIM: Definitions, Overview, Concepts, and Requirements
• RFC 7643 — SCIM: Core Schema
• RFC 7644 — SCIM: Protocol