The SCIM REST API allows for creating and updating Users, Groups (referred to as "Roles" on the front-end dashboard), Organisations, Organisation-Types and Organisation-Users.
A complete list of all schema specifications is accessible via the https://example-tenant.com/ciam/scim/v2/Schemas
endpoint.
A SystemUser
The SystemUser's shared secret token key should be included in the Authorization
HTTP header.
The key should be prefixed by the string literal "Token", with whitespace separating the two strings.
For example: Authorization: Token r454f2529f2cd27e1722e67a624b2b18335e6c21
For POST
and PATCH
request, the Content-Type
HTTP header should be application/json
.
The SystemUser's linked OrganisationUser needs to have the correct CIAM permissions to access the SCIM endpoint.
The response will be in the form of a HTTP UNAUTHORIZED (401).
The response will be in the form of a HTTP FORBIDDEN (403).
In the use case of initial setup, the right order of execution is as follows:
Create the Groups (using POST
on the Groups
endpoint)
Create the OrganisationTypes (using POST
on the OrganisationTypes
endpoint)
Add the Groups to the OrganisationTypes (using PATCH
on the OrganisationTypes
endpoint)
Create the Organisations (using POST
on the Organisations
endpoint)
Add the OrganisationTypes to the Organisations (using PATCH
on the Organisations
endpoint)
Create the Users (using POST
on the Users
endpoint)
Create the OrganisationUsers (using POST
on the OrganisationUsers
endpoint)
Add the OrganisationUsers to the Groups (using PATCH
on the Groups
endpoint)
Schema specification: https://example-tenant.com/ciam/scim/v2/Schemas/urn:connectis:ciam:scim:schemas:core:User
Endpoint: https://example-tenant.com/ciam/scim/v2/Users
Allow: GET
, POST
, PATCH
GET
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Users"
Response:
"status": "200 OK","data": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults": 8,"itemsPerPage": 50,"startIndex": 1,"Resources": [{"id": "14","externalId": null,"schemas": ["urn:connectis:ciam:scim:schemas:core:User"],"userName": "john-doe","name": {"givenName": "John","familyName": "Doe","formatted": "John Doe"},"displayName": "John Doe","emails": [{"value": "[email protected]","primary": true}],"active": true,"meta": {"resourceType": "User","created": "2020-01-30T07:39:53.394952+00:00","lastModified": "2020-01-30T07:39:53.394952+00:00","location": "https://example-tenant.com/ciam/scim/v2/Users/14"}},...]}
POST
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Users","body": {"schemas": ["urn:connectis:ciam:scim:schemas:core:User"],"name": {"givenName": "Jane", "familyName": "Doe"},"emails": [{"value": "[email protected]", "primary": "true"}],"userName": "jane-doe","password": "password"}
Response:
"status": "201 Created","data": {"id": "16","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:core:User"],"userName": "jane-doe","name": {"givenName": "Jane","familyName": "Doe","formatted": "Jane Doe"},"displayName": "Jane Doe","emails": [{"value": "[email protected]","primary": true}],"active": true,"meta": {"resourceType": "User","created": "2020-01-30T08:32:52.503969+00:00","lastModified": "2020-01-30T08:32:52.503969+00:00","location": "https://example-tenant.com/ciam/scim/v2/Users/16"}}
Schema specification: https://example-tenant.com/ciam/scim/v2/Schemas/urn:connectis:ciam:scim:schemas:core:Group
Endpoint: https://example-tenant.com/ciam/scim/v2/Groups
Note: "Groups" are referred to as "Roles" on the front-end dashboard.
Allow: GET
, POST
, PATCH
GET
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Groups"
Response:
"status": "200 OK","data": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults": 4,"itemsPerPage": 50,"startIndex": 1,"Resources": [{"id": "76","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:core:Group"],"displayName": "Test Group","members": [{"value": "13","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/13","display": "Org 1 - John Doe"}],"meta": {"resourceType": "Group","location": "https://example-tenant.com/ciam/scim/v2/Groups/76"},"organisationUsers": [{"value": "13","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/13","display": "Org 1 - John Doe"}],"organisationTypes": [{"value": "6","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6","display": "Test OrganisationType"}]},...]}
POST
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Groups","body": {"schemas": ["urn:connectis:ciam:scim:schemas:core:Group"],"displayName": "Test Group"}
Response:
"status": "201 Created","data": {"id": "76","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:core:Group"],"displayName": "Test Group","members": [],"meta": {"resourceType": "Group","location": "https://example-tenant.com/ciam/scim/v2/Groups/76"},"organisationUsers": [],"organisationTypes": []}
PATCH
example (adding an OrganisationUser to a Group):
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Groups/76","body": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations": [{"op": "add", "path": "organisationUsers", "value": [{"value": "14"}]}]}
Response:
"status": "200 OK","data": {"id": "76","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:core:Group"],"displayName": "Test Group","members": [{"value": "14","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/14","display": "Test Organization - Jane Doe"}],"meta": {"resourceType": "Group","location": "https://example-tenant.com/ciam/scim/v2/Groups/76"},"organisationUsers": [{"value": "14","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/14","display": "Test Organization - Jane Doe"}],"organisationTypes": [{"value": "6","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6","display": "Test OrganizationType"}]}
Note: To remove an OrganisationUser from a Group, change the "add"
to "remove"
in the request body's "Operations"
.
Schema specification: https://example-tenant.com/ciam/scim/v2/Schemas/urn:connectis:ciam:scim:schemas:extension:Organisation
Endpoint: https://example-tenant.com/ciam/scim/v2/Organisations
Allow: GET
, POST
, PATCH
GET
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Organisations"
Response:
"status": "200 OK","data": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults": 5,"itemsPerPage": 50,"startIndex": 1,"Resources": [{"id": "14","externalId": "test.organisation.connectis.nl","schemas": ["urn:connectis:ciam:scim:schemas:extension:Organisation"],"displayName": "Test Organisation","cc": "123","branchNumber": "345","organisationCode": "678","active": true,"organisationUsers": [{"value": "13","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/13","display": "Org 1 - John Doe"}],"organisationTypes": [{"value": "2","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/2","display": "Default"}],"meta": {"resourceType": "Organisation","location": "https://example-tenant.com/ciam/scim/v2/Organisations/14"}},...]}
POST
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Organisations","body": {"schemas": ["urn:connectis:ciam:scim:schemas:extension:Organisation"],"externalId: "test.organisation.connectis.nl","displayName": "Test Organisation","cc": "123","branchNumber": "345","organisationCode": "678","active": true}
Response:
"status": "201 Created","data": {"id": "14","externalId": "test.organisation.connectis.nl","schemas": ["urn:connectis:ciam:scim:schemas:extension:Organisation"],"displayName": "Test Organisation","cc": "123","branchNumber": "345","organisationCode": "678","active": true,"organisationUsers": [],"organisationTypes": [],"meta": {"resourceType": "Organisation","location": "https://example-tenant.com/ciam/scim/v2/Organisations/14"}}
PATCH
example (adding an OrganisationType to an Organisation):
Request:
"url": "https://example-tenant.com/ciam/scim/v2/Organisations/14""body": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations": [{"op": "add", "path": "organisationTypes", "value": [{"value": "6"}]}]}
Response:
"status": "200 OK","data": {"id": "14","externalId": "test.organisation.connectis.nl","schemas": ["urn:connectis:ciam:scim:schemas:extension:Organisation"],"displayName": "Test Organization","cc": "123","branchNumber": "345","organisationCode": "678","active": true,"organisationUsers": [{"value": "14","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/14","display": "Test Organization - Jane Doe"}],"organisationTypes": [{"value": "6","$ref": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6","display": "Test OrganizationType"}],"meta": {"resourceType": "Organisation","location": "https://example-tenant.com/ciam/scim/v2/Organisations/14"}}
Note: To remove an OrganisationType from an Organisation, change the "add"
to "remove"
in the request body's "Operations"
.
Schema specification: https://example-tenant.com/ciam/scim/v2/Schemas/urn:connectis:ciam:scim:schemas:extension:OrganisationType
Endpoint: https://example-tenant.com/ciam/scim/v2/OrganisationTypes
Allow: GET
, POST
, PATCH
GET
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes"
Response:
"status": "200 OK","data": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults": 6,"itemsPerPage": 50,"startIndex": 1,"Resources": [{"id": "6","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationType"],"displayName": "Test OrganisationType","description": "Test OrganisationType description","groups": [{"value": "74","$ref": "https://example-tenant.com/ciam/scim/v2/Groups/74","display": "Admin"}],"organisations": [],"meta": {"resourceType": "OrganisationType","location": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6"}},...]}
POST
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes","body": {"schemas": ["urn:connectis:ciam:scim:schemas:core:OrganisationTypes"],"displayName": "Test OrganisationType","description": "Test OrganisationType description"}
Response:
"status": "201 Created","data": {"id": "6","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationType"],"displayName": "Test OrganisationType","description": "Test OrganisationType description","groups": [{"value": "74","$ref": "https://example-tenant.com/ciam/scim/v2/Groups/74","display": "Admin"}],"organisations": [],"meta": {"resourceType": "OrganisationType","location": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6"}}
PATCH
example (adding a Group to an OrganisationType):
Request:
"url": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6","body": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],"Operations": [{"op": "add", "path": "groups", "value": [{"value": "76"}]}]}
Response:
"status": "200 OK","data": {"id": "6","externalId": "","schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationType"],"displayName": "Test OrganisationType","description": "Test OrganisationType description","groups": [{"value": "74","$ref": "https://example-tenant.com/ciam/scim/v2/Groups/74","display": "Admin"},{"value": "76","$ref": "https://example-tenant.com/ciam/scim/v2/Groups/76","display": "Test Group"}],"organisations": [],"meta": {"resourceType": "OrganisationType","location": "https://example-tenant.com/ciam/scim/v2/OrganisationTypes/6"}}
Note: To remove a Group from an OrganisationType, change the "add"
to "remove"
in the request body's "Operations"
.
Schema specification: https://example-tenant.com/ciam/scim/v2/Schemas/urn:connectis:ciam:scim:schemas:extension:OrganisationUser
Endpoint: https://example-tenant.com/ciam/scim/v2/OrganisationUsers
Allow: GET
, POST
, PATCH
GET
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers"
Response:
"status": "200 OK","data": {"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],"totalResults": 6,"itemsPerPage": 50,"startIndex": 1,"Resources": [{"id": "14","externalId": "ae0a173a-4381-451e-8c86-1efe538380e0","schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationUser"],"displayName": "Test Organisation - Jane Doe","active": true,"organisation": {"value": "14","$ref": "https://example-tenant.com/ciam/scim/v2/Organisations/14","display": "Test Organisation"},"user": {"value": "16","$ref": "https://example-tenant.com/ciam/scim/v2/Users/16","display": "Jane Doe"},"invited_by": {"value": "2","$ref": "https://example-tenant.com/ciam/scim/v2/Users/2","display": "systemuser_0"},"groups": [{"value": "74","$ref": "https://example-tenant.com/ciam/scim/v2/Groups/74","display": "Admin"},],"meta": {"resourceType": "OrganisationUser","location": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/14"}},...]}
POST
example:
Request:
"url": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers","body": {"schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationUser"],"user": "16","organisation": "14","active": true}
Response:
"status": "201 Created","data": {"id": "14","externalId": "ae0a173a-4381-451e-8c86-1efe538380e0","schemas": ["urn:connectis:ciam:scim:schemas:extension:OrganisationUser"],"displayName": "Test Organisation - Jane Doe","active": true,"organisation": {"value": "14","$ref": "https://example-tenant.com/ciam/scim/v2/Organisations/14","display": "Test Organisation"},"user": {"value": "16","$ref": "https://example-tenant.com/ciam/scim/v2/Users/16","display": "Jane Doe"},"invited_by": {"value": "2","$ref": "https://example-tenant.com/ciam/scim/v2/Users/2","display": "systemuser_0"},"groups": [],"meta": {"resourceType": "OrganisationUser","location": "https://example-tenant.com/ciam/scim/v2/OrganisationUsers/14"}}