SCIM API Reference
The product implements basic CRUD operations based on the SCIM 2.0 protocol for managing user identity information. Identity providers like Azure Active Directory can create and update identity information in the product using the SCIM standard and targeting a specific SCIM endpoint for the target environment. This reference topic shows the properties, attributes and operators implemented in the product for these SCIM operations. Use this reference to create your own SCIM-compliant provider to pass user and group identity information to your environment's specific SCIM endpoint.
The SCIM standard contains many more identity attributes than is described here. This topic shows only those attributes that the product uses.
Your environment will have a dedicated SCIM URL, and might have more than one SCIM URL if you have different Identity Providers or different domains to sync with the product. You will receive your environment's SCIM URL and Token value for your environment from Nintex K2 Cloud operations as part of your onboarding process or Identity Provider registration process. Be sure to use the correct URL and endpoint for the operation that you need to implement on your Identity Provider.
In the sample request URls listed in this topic, replace the [placeholder] values with the appropriate values for the environment you are working with:
- [ScimBaseUrl]: the base URL for the SCIM service. It should look something like https://scim.onk2.com. The token will be supplied by the Nintex K2 Cloud operations team when your identity provider is configured in your environment. Look for the scim:baseUrl value in your identity provider confirmation email.
- [token]: a unique, GUID-like value that represents the access token for the targeted environment. It will follow a pattern like ********-****-****-****-************. The token will be supplied by the operations team when your identity provider is configured for your environment. Look for the scim:token value in your identity provider confirmation email.
- [ScimUrl]: combine the ScimBaseURL and the Token value to determine the unique URL for your environment, in the format https://[ScimBaseUrl]/tokens/[token]/scim/v2. For example, the ScmUrl value for a specific environment would look something like https://scim.onk2.com/tokens/********-****-****-****-************/scim/v2
Operations
| Operations | URL for users | URL for groups | HTTP Responses | Notes |
|---|---|---|---|---|
| Service Provider Config | GET {ScimBaseUrl}/scim/v2/ServiceProviderConfig | N/A | 200 OK | |
| Create | POST [ScimUrl]/Users | POST [ScimUrl]/Groups | 201 Success 400 Bad request 409 Conflict |
|
| Get | GET [ScimUrl]/Users/{UserID} | GET [ScimUrl]/Groups/{GroupID} | 200 User/Group exists 400 Bad request 404 Not found |
A GET operation's results are limited to 100 returned items. For example:
|
| Update | PATCH [ScimUrl]/Users/{UserID} | PATCH [ScimUrl]/Group/{GroupID} | 200 Success | Use this operation to Update an existing user/group’s specific properties. This is effectively an UPDATE operation. |
| Delete | DELETE [ScimUrl]/Users/{UserID} | DELETE [ScimUrl]/Groups/{GroupID} | 200 Success | Marks a user or group as Inactive |
| Replace | PUT [ScimUrl]/Users/{UserID} | PUT [ScimUrl]/Groups/{GroupID} | 200 Success | Use this operation to delete existing and insert new user/group properties. When using Replace, all properties omitted will remove those properties from the result. To Replace correctly, first Get the resource, modify its result and use that as the body for the Replace operation. |
K2 core properties
The product maps the following core properties to SCIM standard properties:
| Property | SCIM property |
|---|---|
| Name | Username |
| DisplayName | DisplayName |
| Primary Email | |
| ScimID | ID |
| ExternalID | ExternalID |
Filters
Use the Filter property to apply filters to GET requests. Filter results using an attribute, operator and value. You can combine filters with logical AND/OR operators and brackets.
| Sample URL | Attributes | Operators | Logical Operators | |
|---|---|---|---|---|
| GET /Users |
GET [ScimUrl]/Users?filter={attribute}{op}{value}
You can combine filters with logical AND, OR and brackets:
|
|
|
|
| GET /Groups |
GET [ScimUrl]/Groups?filter={attribute}{op}{value} |
|
|
|
HTTP Responses
- 200 Success
- 201 Success
- 400 Bad request
- 404 Not found
- 409 Conflict
Request header parameters
| Parameter | Type | Description |
|---|---|---|
| Authorization | String | Set to Bearer <token> |
| Content-Type | String | Set to application/scim+json |
| Accept | String | Set to application/scim+json |
API reference
Get the Service Provider ConfigConsiderations
- You will need to replace the value of [token] in the endpoint URIs with a valid token value for the identity provider you are working with. The token will be supplied by the K2 Cloud operations team when your identity provider is configured in your K2 Cloud environment. It will be a guid value, look for the scim:token value in your identity provider confirmation email.
- The active property will be omitted from the response if the user is disabled. A 404 will be returned if a user was deleted. The active property will be returned and have a value of true when the user is enabled.
- Users will only be able to authenticate with the product once their user information has synchronized between the Identity Provider and the product. The SCIM application is responsible for sending updated user information to the product as necessary, to ensure that user information is kept synchronized.
-
Known Issue
Issue:
An error occurs when trying to access group details using a URL such as: 'https://scim.onk2.com/tokens/{{token}}/scim/v2/Groups?filter=DisplayName eq CL_Sell in - Purchase Supervisor' for example. This happens when:- The URL ends with OR or AND, and containing a space
- The URL contains "OR " or "AND " (with a space after the keyword)
"...Status:400 error scimType: InvalidValue Detail: "Value cannot be null.\r\nParameter name: text..."
Workaround:
Add a double quote for the group name that has the issue, for example:filter=DisplayName eq CL_Sell in - Purchase Supervisor
must be:
filter=DisplayName eq "CL_Sell in - Purchase Supervisor"