SCIM API

Introduction

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.

Actors

  • A SystemUser

Preconditions

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

Exceptions

No secret token (or an incorrect one) is included in the request's header.

  1. The response will be in the form of a HTTP UNAUTHORIZED (401).

A secret token is included in the request's header but the SystemUser's OrganisationUser doesn't have the right CIAM permissions.

  1. The response will be in the form of a HTTP FORBIDDEN (403).

Order of Execution

In the use case of initial setup, the right order of execution is as follows:

  1. Create the Groups (using POST on the Groups endpoint)

  2. Create the OrganisationTypes (using POST on the OrganisationTypes endpoint)

  3. Add the Groups to the OrganisationTypes (using PATCH on the OrganisationTypes endpoint)

  4. Create the Organisations (using POST on the Organisations endpoint)

  5. Add the OrganisationTypes to the Organisations (using PATCH on the Organisations endpoint)

  6. Create the Users (using POST on the Users endpoint)

  7. Create the OrganisationUsers (using POST on the OrganisationUsers endpoint)

  8. Add the OrganisationUsers to the Groups (using PATCH on the Groups endpoint)

Endpoints

Users

  • 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": "john-doe@test.com",
      "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": "jane-doe@test.com", "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": "jane-doe@test.com",
      "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"
      }
      }

Groups

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

Organisations

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

Organisation-Types

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

Organisation-Users

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