Troubleshoot the SCIM API

SCIM errors usually indicate authentication issues, unsupported SCIM operations, invalid user data, entitlement problems, or conflicts between Anaplan and your identity provider.

The SCIM API returns errors in a standard SCIM error format. A typical error response includes a schemas value, a human-readable detail message, and an HTTP status code.

Some errors include a scimType field that provides additional context.

Authentication failures usually occur when the authorization header is missing, malformed, expired, or uses credentials for a user that cannot call the SCIM API.

Check that:

• The request includes a supported authorization method: Basic authentication, AnaplanAuthToken, or API key bearer token.
• The authentication value is correctly formatted.
• The calling user is an active Anaplan non-SSO user where required.
• The calling user has the recommended User Admin role.
• The token or API key has not expired or been revoked.

Example authorization headers:

Authorization: BASIC <username:password base64 encoded>
Authorization: AnaplanAuthToken <token>
Authorization: Bearer <API key>


A 404 error can occur when the requested user ID does not exist, the user is not visible to the caller, or the URL path is incorrect.

Check that:

• The user ID in /Users/{id} is correct.
• The endpoint uses Users with a capital U.
• The base URL is correct: https://api.anaplan.com/scim/1/0/v2.
• The caller has permission to view the user.
• The user has not been deleted or disabled in a way that affects retrieval.

A user creation request can fail if required SCIM user attributes are missing or if the user already exists.

Check that the request includes:

• schemas
• userName
• name.givenName
• name.familyName
• Any required entitlement data, if assigning workspaces during creation

Also check whether the user already exists in Anaplan. A duplicate user can result in a 409 Conflict.

Workspace entitlement issues usually happen when the entitlement format is invalid, a workspace ID or workspace name is incorrect, or too many workspaces are included in a single request.

Check that:

• The workspace ID or workspace name exists in the tenant.
• The entitlement type is one of the supported values:
  • WORKSPACE
  • WORKSPACE_IDS
  • WORKSPACE_NAMES
• The request does not exceed the documented limit of 50 workspaces per call.
• For WORKSPACE, each entitlement object includes a workspace ID in value or a workspace name in display.
• For WORKSPACE_IDS, the value contains a comma-separated list of workspace IDs.
• For WORKSPACE_NAMES, the value contains a comma-separated list of workspace names.

This can happen when replacing a user with PUT. A replace request sends the full desired state of the user. If entitlements are omitted from the request body, the user can be removed from associated workspaces.

To avoid this issue:

• Use GET /Users/{id} to retrieve the current user record before replacing it.
• Include all workspace entitlements that the user should keep.
• Use PATCH /Users/{id} for targeted entitlement changes when you do not want to replace the full user record.

Patch requests can fail when the operation, path, or value is invalid. In Anaplan’s implementation, path is always required.

Check that:

• The request body uses the SCIM PatchOp schema.
• Each operation includes a supported op: add, replace, or remove.
• Each operation includes a valid path.
• The Content-Type header is set to application/scim+json.
• Entitlement paths and filters are correctly formed.

Example:

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


The SCIM API supports only selected filter fields and operators. Unsupported fields or operators can cause errors or unexpected empty results.

Supported filter fields include:

• id
• externalId
• userName
• name.familyName
• name.givenName
• active

Supported operators include:

• Eq
• Ne
• Pr
• Gt
• Ge
• Lt
• Le

The following are not supported:

• Complex attribute filtering with []
• not
• Some filter fields, such as displayName and entitlement fields
• Some operators, such as Co, Sw, and Ew
• Search with POST, such as /.search or /Users/.search

A 406 Not Acceptable error can occur if the request asks for a response format the SCIM API does not support.

Use one of these headers:

Accept: application/scim+json
Accept: application/json


Do not request unsupported response formats such as XML.

This can happen when Anaplan and the identity provider are both used to update user attributes or workspace entitlements.

To avoid unexpected overwrites:

• Decide which system is the system of record for user attributes and entitlement assignments.
• Avoid manually changing synchronized fields in Anaplan if the identity provider will overwrite them later.
• Align identity provider mappings with the fields you intend to manage through SCIM.
• Review attribute mappings for userName, externalId, name.givenName, name.familyName, active, and entitlements.

Entitlement updates are not atomic. User data and entitlement data are stored separately, so a request can partially succeed if user data is saved but entitlement updates fail.

When this happens:

• Review the response body for the part of the request that failed.
• Retrieve the user record again with GET /Users/{id}.
• Confirm whether the user attributes were updated.
• Retry only the failed entitlement update once the cause is corrected.