SCIM API Reference

Microsoft Azure Active Directory is now Microsoft Entra ID

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 see your environment's SCIM URL on the SCIM API page in Management after it is enabled. The Provider Instance ID is for the Provider Instance that was configured for the Sync Provider. 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.{yourdomain}.com and can be found on the SCIM API page.
[provinstid]: a unique, id value that represents the provider instance for the provider that was configured on the environment. It will be a number like 11.
[ScimUrl]: combine the ScimBaseURL and the ProvInstID 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.{yourdomain}.com/api/scim/v2/**

Operations

Operations	URL for users	URL for groups	HTTP responses	Notes
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: GET /users returns at most 100 users GET /groups returns at most 100 groups, each group with at most 100 users. This could potentially return 10 000 results (100 groups x 100 users per group) The results are ordered alphabetically, first by displayName then by Name if a displayName does not exist.
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
Email	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?ﬁlter={attribute}{op}{value}	username displayname externalid urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.displayName urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.value email id	eq (Equals) co (Contains)	and or
GET /Groups	GET [ScimUrl]/Groups?ﬁlter={attribute}{op}{value}	DisplayName ExternalId members[value {op} {ID}] members[display {op} {value}] id	eq (Equals) co (Contains)	and or

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

The Bearer token and SCIM token are two different values.

API reference

Create user

The API uses the JSON request body of the operation to create the user in the identity store if the user object is not found. If successful, the response contains the user's profile.

Resource endpoint

POST [ScimUrl]/Users

HTTP response status codes

201	Success
400	Bad request
409	Conflict

Copy

Create user sample request body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "username": "PhantomUserName",
  "displayName": "PhantomdisplayName",
  "active": true,
  "emails": [
    {
      "value": "Phantom@email.com",
      "primary": true,
      "type": "work"
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "manager": {
      "value": "14E7125BD0E4BA09B254D286F6CB8028C3460858F3BB1023495F8772CFE86A37"
    }
  },
  "externalId": "ph5be63c-017b-4947-a399-38ee7235f0fe"
}

Copy

Create user sample response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "id": "DF778BA9C32B59029C85DB9CF56C1C205AE52F5440ADC8D7DAADD62A7D2D9C2C",
  "meta": {
    "resourceType": "User",
    "location": "/tokens/d6567e42-53f9-4f82-b23e-62ad049bfe17/scim/v2/users/DF778BA9C32B59029C85DB9CF56C1C205AE52F5440ADC8D7DAADD62A7D2D9C2C"
  },
  "externalId": "ph5be63c-017b-4947-a399-38ee7235f0fe",
  "userName": "PhantomUserName",
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "manager": {
      "value": "14E7125BD0E4BA09B254D286F6CB8028C3460858F3BB1023495F8772CFE86A37",
      "$ref": "users/14E7125BD0E4BA09B254D286F6CB8028C3460858F3BB1023495F8772CFE86A37",
      "displayName": " PhantomenterpriseUserdisplayName"
    }
  },
  "displayName": "PhantomdisplayName",
  "active": true,
  "emails": [
    {
      "value": "Phantom@email.com",
      "primry": true,
      "type": "work"
    }
  ]
}

Create Group

The API uses the JSON request body of the operation to create a group in the identity store.

Resource endpoint

POST [ScimUrl]/groups

HTTP response status codes

201	Created
400	Bad request
409	Conflict

Copy

Sample request body

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "externalId": "g225511c-d3e0-41e2-99f2-9f7d679e6d9f",
  "displayName": "PhantomGroupDisplay",
  "members": [
    {
      "value" : "F109C958D5A4796B81E466DA743B1235481AFBD79C3D7748A2BA5F87D8E848D2"
    }
  ]
}

Copy

Sample 201 Created response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952",
  "meta": {
    "resourceType": "Group",
    "location": "/tokens/d6567e42-53f9-4f82-b23e-62ad049bfe17/scim/v2/groups/564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952"
  },
  "externalId": "g225511c-d3e0-41e2-99f2-9f7d679e6d9f",
  "displayName": "PhantomGroupDisplay",
  "members": [
    {
      "value" : "F109C958D5A4796B81E466DA743B1235481AFBD79C3D7748A2BA5F87D8E848D2"
      "$ref" : "users/F109C958D5A4796B81E466DA743B1235481AFBD79C3D7748A2BA5F87D8E848D2"
      "display" : "GroupMember1"
    }
  ]
}

Get user by ID

The API uses the supplied ID and other query parameters to retrieve a specific user. The operation also verifies the user exists.

The active property will be omitted from the response if the user is disabled. A 404 error 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.

Resource endpoint

GET [ScimUrl]/users/{userId}

HTTP response status codes

200	Success
400	Bad request
404	Not found

Copy

Get user by ID sample response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "A8CFCBCF0B6F4641DD0DB7243B08B0EE8F5BB172CB8B9E8D773415C88EAA394F",
  "meta": {
    "resourceType": "User",
    "location": "/tokens/{tokenId}/scim/v2/users/A8CFCBCF0B6F4641DD0DB7243B08B0EE8F5BB172CB8B9E8D773415C88EAA394F"
  },
  "externalId": "",
  "userName": "user",
  "displayName": "jbibinka",
  "active": true,
  "emails": [
    {
      "value": "jbibinka2@example.com",
      "primary": true,
      "type": "work"
    }
  ]
}

Get user using a filter

The API uses the supplied filter properties to retrieve a specific user. The operation also verifies the user exists.

Resource endpoint

GET [ScimUrl]/users?ﬁlter={attribute}{op}{value}

GET [ScimUrl]/users?ﬁlter={attribute}{op}{value} AND {attribute}{op}{value}

Filter properties

Attributes	Operators	Values
username displayname externalid urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.displayName urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.value email id	eq (Equals) co (Contains)	username displayname externalid urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.displayName urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.value email id

HTTP response status codes

200	Success
400	Bad request

Copy

Get user using a filter sample response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "A15F6D1D2A192384F851B861177372EADCFAA0CC1C97BDFA4D9B50249E836743",
      "meta": {
        "resourceType": "User",
        "location": "/tokens/{tokenId}/scim/v2/users/A15F6D1D2A192384F851B861177372EADCFAA0CC1C97BDFA4D9B50249E836743"
      },
      "externalId": "",
      "userName": "user1",
      "displayName": "jbibinka",
      "active": true,
      "emails": [
        {
          "value": "jbibinka2@example.com",
          "primary": true,
          "type": "work"
        }
      ]
    }
  ]
}

Get Group by ID

The API uses the supplied ID and other query parameters to retrieve a specific group. The operation also verifies the group exists.

Resource endpoint

GET [ScimUrl]/groups/{groupID}

HTTP response status codes

200	Success
400	Bad request
404	Not found

Copy

Get group by ID sample response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952",
  "meta": {
    "resourceType": "Group",
    "location": "/tokens/{tokenId}/scim/v2/groups/564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952"
  },
  "externalId": "g225511c-d3e0-41e2-99f2-9f7d679e6d9f",
  "displayName": "PhantomGroupDisplay",
  "members": []
}

Get group using a filter

The API uses the supplied filter properties to retrieve a specific group. The operation also verifies the group exists.

Resource endpoint

GET [ScimUrl]/Groups?ﬁlter={attribute}{op}{value}

GET [ScimUrl]/Groups?ﬁlter={attribute}{op}{value} AND {attribute}{op}{value}

Filter properties

Attributes	Operators	Values
ID DisplayName ExternalID urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.displayName urn:ietf:params:scim:schemas:extension:enterprise:2.0:user:manager.value	eq (Equals) co (Contains)	DisplayNames ExternalId ScimId

HTTP response status codes

200	Success
400	Bad request

Copy

Get group using a filter sample response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952",
      "meta": {
        "resourceType": "Group",
        "location": "/tokens/{tokenId}/scim/v2/groups/564E146537437A2AA02C110303ACAD2AE37E5B363113EFACDB303759EE036952"
      },
      "externalId": "g225511c-d3e0-41e2-99f2-9f7d679e6d9f",
      "displayName": "PhantomGroupDisplay",
      "members": []
    }
  ]
}

Replace User

The API uses the supplied ID to identify the user who's entry will be replaced/updated with new values.

Resource endpoint

PUT [ScimUrl]/Users/{UserID}

HTTP response status codes

200	Success
400	Bad request
409	Conflict

Even though UserID is part of the resource endpoint URL, the id value is still required in the body.

Copy

Replace user sample request body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "schemas": [
    "string"
  ],
  "id": "string",
  "userName": "string",
  "displayName": "string",
  "active": true,
  "emails": [
    {
      "value": "string",
      "type": "string",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "manager": {
      "value": "string"
    }
  }
}

Copy

Replace user sample success response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "schemas": [
    "string"
  ],
  "id": "string",
  "meta": {
    "resourceType": "string",
    "lastModified": "string",
    "location": "string"
  },
  "externalId": "string",
  "userName": "string",
  "displayName": "string",
  "active": true,
  "emails": [
    {
      "value": "string",
      "type": "string",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "manager": {
      "value": "string",
      "display": "string",
      "$ref": "string"
    }
  }
}

Replace Group

The API uses the supplied ID to identify the group to be replaced/updated with new values.

Resource endpoint

PUT [ScimUrl]/Groups/{GroupID}

HTTP response status codes

200	Success
400	Bad request
409	Conflict

Copy

Replace group sample request body

1
2
3
4
5
6
7
8
9
10
11
12
{
  "schemas": [
    "string"
  ],
  "id": "string",
  "displayName": "string",
  "members": [
    {
      "value": "string"
    }
  ]
}

Copy

Replace group sample success response body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "schemas": [
    "string"
  ],
  "id": "string",
  "meta": {
    "resourceType": "string",
    "lastModified": "string",
    "location": "string"
  },
  "externalId": "string",
  "displayName": "string",
  "members": [
    {
      "value": "string",
      "display": "string",
      "$ref": "string"
    }
  ]
}

Considerations

The active property will be omitted from the response if the user is disabled. A 404 error 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)
Error:
"...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"