SCIM API Reference

The product implements basic CRUD operations based on the SCIM 2.0 protocol for managing user identity information. Identity providers like AAD 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:
  • 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?filter={attribute}{op}{value}

  • GET [ScimUrl]/Users?filter={attribute}{op}{value}
    e.g.
    GET [ScimUrl]/Users?filter=username eq someusername

You can combine filters with logical AND, OR and brackets:

  • GET [ScimUrl]/Users?filter={attribute}{op}{value} and {attribute}{op}{value}
    e.g.
    GET [ScimUrl]/Users?filter=externalId eq 123 and username co somevalue
  • GET [ScimUrl]/Users?filter={attribute}{op}{value} or {attribute}{op}{value}
    e.g.
    GET [ScimUrl]/Users?filter=externalId eq 123 or externalId eq 456
  • GET [ScimUrl]/Users?filter={attribute}{op}{value} and ({attribute}{op}{value} or {attribute}{op}{value})
    e.g.
    GET [ScimUrl]/Users?filter=username co somevalue and (externalId co 123 or email ew com)
  • 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)
  • ew
    (Ends With)
  • sw
    (Starts With)
  • and
  • or
GET /Groups

GET [ScimUrl]/Groups?filter={attribute}{op}{value}
  • DisplayName
  • ExternalId
  • members[value {op} {ID}]
  • members[display {op} {value}]
  • id
  • eq (Equals)
  • co (Contains)
  • ew
    (Ends With)
  • sw
    (Starts With)

  • 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

The SCIM ServiceProviderConfig endpoint is a SCIM discovery mechanism that returns a JSON structure that describes the SCIM operations and authentication methods. Use an HTTP GET to this endpoint to return the information.

See section 4: Service Provider Configuration Endpoints and section 5: Service Provider Configuration Schema of the official SCIM standard documentation for definitions and more information.

Resource endpoint

GET {ScimBaseUrl}/scim/v2/ServiceProviderConfig

(Note that this operation does not require the token value)

HTTP response status codes

200 OK

Sample response body

Copy

Get the Service Provider Config sample response body

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"
    ],
    "documentationUri": "https://k2.com/help/identity/scim/serviceproviderconfig/documentationURI",
    "patch": {
        "supported": true
    },
    "bulk": {
        "supported": false,
        "maxOperations": 0,
        "maxPayloadSize": 0
    },
    "filter": {
        "supported": true,
        "maxResults": 0
    },
    "changePassword": {
        "supported": false
    },
    "sort": {
        "supported": false
    },
    "etag": {
        "supported": false
    },
    "authenticationSchemes": [
        {
            "type": "oauthbearertoken",
            "name": "OAuth Bearer Token",
            "description": "Authentication scheme using the OAuth Bearer Token Standard",
            "documentationUri": "https://k2.com/help/identity/scim/authenticationschemes/documentationURI"
        }
    ],
    "meta": {
        "resourceType": "ServiceProviderConfig",
        "location": "http://localhost:8714/api/v1.0/serviceproviderconfig"
    }
}

                        

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

{
  "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

{
  "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"
    }
  ]
}

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

{
  "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

{
  "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"
    }
  ]
}

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 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

{
  "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"
    }
  ]
}

The API uses the supplied filter properties 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 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?filter={attribute}{op}{value}

GET [ScimUrl]/users?filter={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)
  • ew
    (Ends With)
  • sw
    (Starts With)
  • 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

{
  "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"
        }
      ]
    }
  ]
}

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

{
  "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": []
}

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

Resource endpoint

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

GET [ScimUrl]/Groups?filter={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)
  • ew
    (Ends With)
  • sw
    (Starts With)
  • DisplayNames
  • ExternalId
  • ScimId

HTTP response status codes

200 Success
400 Bad request

Copy

Get group using a filter sample response body

{
  "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": []
    }
  ]
}

The API uses the supplied ID to mark an existing user as inactive.

Resource endpoint

DELETE [ScimUrl]/users/{userId}

HTTP response status codes

204 Success
400 Bad Request
404 Not Found

The API uses the supplied ID to mark an existing group as inactive.

Resource endpoint

DELETE [ScimUrl]/groups/{groupId}

HTTP response status codes

204 Success
400 Bad Request
404 Not Found

The API uses the supplied ID to replace details of the user with new values.

Resource endpoint

PATCH [ScimUrl]/Users/{UserID}

HTTP response status codes

200 Success

Sample request body

Copy

Multiple Update/Patch requests in one request body, sample

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager",
      "value": 
      {
        "value": "[ManagerScimID]"
      }
    },
    {
      "op": "add",
      "path": "emails",
      "value": 
      [
        {
          "value": "PrimaryMail@mymail.com",
          "type": "work",
          "primary": true
        },
        {
          "value": "HomeMail@mymail.com",
          "type": "home",
          "primary": false
        },
        {
          "value": "PrivateMail@mymails.com",
          "type": "private",
          "primary": false
        }
      ]
    },
    {
      "op": "replace",
      "path": "displayName",
      "value": "UpdatedDisplayname"
    },
    {  
      "op": "replace",
      "path": "emails[type eq \"home\" or value ew \"mymails.com\"]",
      "value": 
      {
        "type": "string"
      }   
    },
    {
      "op": "remove",
      "path": "emails[type eq \"work\"]"
    },
    {
      "op": "replace",
      "path": "externalId",
      "value": "e68a5c1f-63a9-41ea-90f0-ab2bd5fd7749"
    }
  ]
}
Patching any email primary property to true will set all other primary properties to false. If you set more than one primary to true, only the last evaluated email’s primary will be set to true and everything else to false.

Sample response body

Copy

Response body for sample header above

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
    ],
    "id": "27035AB74DA2D3B7653EBAC343F0449B7E32BE608F5CC33378F0F9F5E2F0849F",
    "meta": {
        "resourceType": "User",
        "lastModified": "2020-09-10T11:42:47.3461594Z",
        "location": "/tokens/c29a233f-999f-411f-951e-8f38b18228c8/scim/v2/users/27035AB74DA2D3B7653EBAC343F0449B7E32BE608F5CC33378F0F9F5E2F0849F"
    },
    "externalId": "e68a5c1f-63a9-41ea-90f0-ab2bd5fd7749",
    "userName": "baseuser",
    "displayName": "UpdatedDisplayname",
    "active": true,
    "emails": [
        {
            "value": "HomeMail@mymail.com",
            "type": "string"
        },
        {
            "value": "PrivateMail@mymails.com",
            "type": "string",
            "primary": true
        }
    ],
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
        "manager": {
            "value": "B17571C70B6AB37946642D47670A34C7B2E6B9B09C0CA9D9484A0F9FD87EA95F",
            "$ref": "users/B17571C70B6AB37946642D47670A34C7B2E6B9B09C0CA9D9484A0F9FD87EA95F",
            "displayName": "string"
        }
    }
}

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

{
  "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

{
  "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"
    }
  }
}

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

{
  "schemas": [
    "string"
  ],
  "id": "string",
  "displayName": "string",
  "members": [
    {
      "value": "string"
    }
  ]
}

Copy

Replace group sample success response body

{
  "schemas": [
    "string"
  ],
  "id": "string",
  "meta": {
    "resourceType": "string",
    "lastModified": "string",
    "location": "string"
  },
  "externalId": "string",
  "displayName": "string",
  "members": [
    {
      "value": "string",
      "display": "string",
      "$ref": "string"
    }
  ]
}

Considerations

  • 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)
    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"