Skip to main content

Connect a Custom SCIM Application

In addition to supporting integration with popular SCIM provisioning platforms like Okta and Entra ID, Tonkean provides an internal SCIM API for custom applications. This reference topic provides the relevant endpoints, request values, and samples to support the creation of a custom SCIM application for Tonkean user provisioning.

Tonkean provides the following SCIM endpoints:

  • Provision / create user

  • Deprovision / disable user

  • Update user fields

  • Provision user groups

  • Update user group fields

  • Update user group memberships (add/remove users from groups)

  • Delete user groups

For information regarding the SCIM protocol and API, see the SCIM public documentation.

Create and Configure the Identity Provider

To get started, you must create and configure a new identity provider in Tonkean, generating an API token.

  1. In Tonkean, select your user profile in the upper right, then select Board Settings. The Board Settings screen displays.

    custom_scim_board_settings_select.png

  2. In the sidenav, select Identity Provider. The Identity Provider screen displays.

    custom_scim_id_provider_select.png

  3. Locate the SCIM API url and select Copy to copy the value. Save this URL in an external document; this is the BASE_URL.

    custom_scim_copy_scim_api_url.png

  4. Select Create New Provider. The Create New Provider window displays.

    id_provider_create_new_provider.png

  5. Select the Provider Type dropdown and choose Custom, enter a Display Name, then select Generate Token. The Access Token displays.

    custom_scim_create_new_provider_config.png

  6. Select Copy to copy the Access Token. Save this token in an external document; this is the ACCESS_TOKEN.

    This is the last time you'll be able to view the decrypted token, so make sure you save it somewhere safe in case you need to reference it later.

    custom_scim_access_token.png

Users

This section provides information on provisioning, deprovisioning, and updating users in Tonkean.

User Payload

Below is the payload of the “User” entity in the SCIM protocol as it is expected to be sent and received in the SCIM endpoints.

{
     "id": "PRSNxxxyyyzzz",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "custom_user_id",
    "userName": "custom_user_id",
    "displayName": "John Smith",
    "name": {
        "familyName": "John",
        "givenName": "Smith"
    },
    "emails": [
        {
            "value": "john.smith@acme.com",
            "primary": true,
            "type": "work"
        }
    ],
    "active": "true",
    "meta": {
        "resourceType": "User",
        "created": 1740706716
    },
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "Tonkean": "PROCESS_CONTRIBUTOR,SYSTEM_USER"
    }
}

User Payload Fields

Field Name

Type

Input

Description

id

Tonkean ID

false

The Tonkean ID of the user. Returned in CREATE response.

Used for update/delete endpoints in the URL.

schemas

SCIM schema

true

Value required as part of SCIM protocol. Value should always be:

["urn:ietf:params:scim:schemas:core:2.0:User"]

externalId

String

true

Field used for audit and reference. Will not be displayed in Tonkean. Can be used for custom user id.

userName

String

true

Field used for audit and reference. If no email is provided in emails field and this contains a valid email address, will take the email from this field.

displayName

String

true

Full name to use as the user name in the Tonkean app. Usually should be in format of “FirstName LastName” (for example, “John Smith”).

name

JSON

true

JSON that contains the familyName and givenName fields representing the name of the user. While this is stored, Tonkean is currently using displayName in the app.

emails

JSON Array

true

Array of JSON elements containing the list of emails for the user. Tonkean will only use the email marked with primary=true.

active

boolean

true

Value expected is true. If false, user will be created as “disabled”.

meta

JSON

false

A JSON element containing metadata properties returned from Tonkean backend.

urn:ietf:params:scim:schemas:extension:enterprise

JSON

true

A JSON element with a single field called “Tonkean” that contains the roles to be set for this user in Tonkean.

Possible values are:

  • PROCESS_CONTRIBUTOR 

  • SYSTEM_USER 

  • PROCESS_CONTRIBUTOR,SYSTEM_USER 

NOTE: User can be created without any roles and then roles can be assigned via “instant access” or via group membership.

urn:scim:tonkean

JSON

false

Old value used for Tonkean roles. Used only for backward compatibility. Please ignore.

Provision / Create User

This is the endpoint to create a new user in Tonkean.

POST: {BASE_URL}/Users (for example, https://api.tonkean.com/scim/v2/Users)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "custom_user_id",
    "userName": "custom_user_id",
    "displayName": "John Smith",
    "name": {
        "familyName": "John",
        "givenName": "Smith"
    },
    "emails": [
        {
            "value": "john.smith@acme.com",
            "primary": true,
            "type": "work"
        }
    ],
    "active": "true",
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "tonkean": "PROCESS_CONTRIBUTOR,SYSTEM_USER"
    }
}

Response Example

{
    "id": "PRSNyR6viFqBO73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "custom_user_id",
    "name": {
        "givenName": "Smith",
        "familyName": "John"
    },
    "emails": [
        {
            "primary": true,
            "value": "john.smith@acme.com",
            "type": "work"
        }
    ],
    "displayName": "John Smith",
    "externalId": "custom_user_id",
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": 1740706716
    },
    "urn:scim:tonkean": {
        "tonkeanRoles": [
            "PROCESS_CONTRIBUTOR",
            "SYSTEM_USER"
        ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "Tonkean": "[PROCESS_CONTRIBUTOR, SYSTEM_USER]"
    }
}

Replace User

This is the endpoint to replace all the data for an existing user in Tonkean.

PUT: BASE_URL}/Users/{TonkeanUserID} (for example, https://api.tonkean.com/scim/v2/Users/PRSNyR6viFqBO73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "externalId": "custom_user_id_new_value",
    "userName": "custom_user_id_new_value",
    "displayName": "John Smith_new_value",
    "name": {
        "familyName": "John_new_value",
        "givenName": "Smith_new_value"
    },
    "emails": [
        {
            "value": "john.smith@acme.com",
            "primary": true,
            "type": "work"
        }
    ],
    "active": "true",
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "tonkean": "PROCESS_CONTRIBUTOR"
    }
}

Response Example

{
    "id": "PRSNyR6viFqBO73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "custom_user_id_new_value",
    "name": {
        "givenName": "Smith_new_value",
        "familyName": "John_new_value"
    },
    "emails": [
        {
            "primary": true,
            "value": "john.smith@acme.com",
            "type": "work"
        }
    ],
    "displayName": "John Smith_new_value",
    "externalId": "custom_user_id_new_value",
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": 1740706716
    },
    "urn:scim:tonkean": {
        "tonkeanRoles": [
            "PROCESS_CONTRIBUTOR"
        ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "Tonkean": "[PROCESS_CONTRIBUTOR]"
    }
}

Update User

Partially update data for an existing user in Tonkean.

PATCH: {BASE_URL}/Users/{TonkeanUserID} (for example, https://api.tonkean.com/scim/v2/Users/PRSNyR6viFqBO73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

For a helpful resource for PATCH calls in SCIM, see SCIM 2.0 Patch Operations.

Request Example

{
     "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":[
        {
        "op": "replace",
        "path": "displayName",
        "value": "bla bla"
        }
    ]
}

Response Example

{
    "id": "PRSNyR6viFqBO73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "custom_user_id_new_value",
    "name": {
        "givenName": "Smith_new_value",
        "familyName": "John_new_value"
    },
    "emails": [
        {
            "primary": true,
            "value": "john.smith@acme.com",
            "type": "work"
        }
    ],
    "displayName": "bla bla",
    "externalId": "custom_user_id_new_value",
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": 1740706716
    },
    "urn:scim:tonkean": {
        "tonkeanRoles": [
            "PROCESS_CONTRIBUTOR"
        ]
    },
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "Tonkean": "[PROCESS_CONTRIBUTOR]"
    }
}

Disable / Deprovision User

Disable a user in Tonkean.

Users cannot be deleted in Tonkean—only disabled.

DELETE: {BASE_URL}/Users/{TonkeanUserID} (for example, https://api.tonkean.com/scim/v2/Users/PRSNyR6viFqBO73)

Authorization: Bearer {ACCESS_TOKEN}

Request Example

—

Response Example

204 No Content

Get Users

Get existing users in Tonkean.

GET: {BASE_URL}/Users/

Authorization: Bearer {ACCESS_TOKEN}

Query Params:

Param Name

Default

Description

startIndex

1

Index to start listing users from.

count

100

Amount of items to return in the call.

filter

—

Only supported filter: userName.

Request Example

—

Response Example

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 3,
    "startIndex": 1,
    "itemsPerPage": 100,
    "Resources": [
        {...},
        {...},
    ]
}

Get Users by Tonkean ID

Get user details in Tonkean based on tonkean Id (for example, PRSNxcafa).

Request Example

—

Response Example

{
    "id": "PRSNyR6viFqBO73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "userName": "custom_user_id_new_value",
    "name": {
        "givenName": "Smith_new_value",
        "familyName": "John_new_value"
    },
    "emails": [
        {
            "primary": true,
            "value": "john.smith@acme.com",
            "type": "work"
        }
    ],
    "displayName": "bla bla",
    "externalId": "custom_user_id_new_value",
    "active": true,
    "meta": {
        "resourceType": "User",
        "created": 1740706716
    },
    "urn:scim:tonkean": {
        "tonkeanRoles": []
    },
    "urn:ietf:params:scim:schemas:extension:enterprise": {
        "Tonkean": "[]"
    }
}

Groups

This section provides information on provisioning, deprovisioning, and updating user groups in Tonkean.

Group Payload

Below is the payload of the “Group” entity in the SCIM protocol as it is expected to be sent and received in the SCIM endpoints.

{
    "id": "SCGRxxxyyyzzz",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJxxxyyyzzz",
    "members": [

]
}

Group Payload Fields

Field Name

Type

Input

Description

id

Tonkean ID

false

The tonkean ID of the group. Returned in CREATE response.

Used for update/delete endpoints in the URL.

schemas

SCIM schema

true

Value required as part of SCIM protocol. Value should always be:

["urn:ietf:params:scim:schemas:core:2.0:Group"] 

externalId

String

true

Field used for audit and reference. Will not be displayed in Tonkean. Can be used for custom group id.

displayName

String

true

Full name to use as the group name in the Tonkean app. 

members

JSON Array

true

Array of JSON elements containing the list of members in the group. 

NOTE:Can’t be set on CREATE; only on update.

projectId

Tonkean Id

false

The ID of the Tonkean board associated to this group. Only returned from Tonkean, not input.

Provision / Create Group

Create a new group in Tonkean.

POST: {BASE_URL}/Groups (for example, https://api.tonkean.com/scim/v2/Groups)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "My Admins",
  "externalId": "custom_id"
}

Response Example

{
    "id": "SCGRospWarMpa73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": []
}

Add Member to Group

Add a user as a member of a specified group.

PATCH: {BASE_URL}/Groups/{TonkeanGroupId} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRospWarMpa73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "PRSNyR6viFqBO73"
                }
            ]
        }
    ]
}

Response Example

{
    "id": "SCGRospWarMpa73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": [
        {
            "value": "PRSNyR6viFqBO73"
        }
    ]
}

Remove Member from Group

Remove a user from a specified group.

PATCH: {BASE_URL}/Groups/{TonkeanGroupId} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRospWarMpa73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "remove",
            "path": "members",
            "value": [
                {
                    "value": "PRSNyR6viFqBO73"
                }
            ]
        }
    ]
}

Response Example

{
    "id": "SCGRospWarMpa73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": []
}

Set List of Members in a Group

Set the list of members in an existing group in Tonkean.

PATCH: {BASE_URL}/Groups/{TonkeanGroupId} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRospWarMpa73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "members",
            "value": [
                {
                    "value": "PRSNyR6viFqBO73"
                }
            ]
        }
    ]
}

Response Example

{
    "id": "SCGRospWarMpa73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": [
        {
            "value": "PRSNyR6viFqBO73"
        }
    ]
}

Update Group Name

Update the display-name of an existing group in Tonkean.

PATCH: {BASE_URL}/Groups/{TonkeanGroupId} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRospWarMpa73)

Authorization: Bearer {ACCESS_TOKEN}

Content-Type: application/json

Request Example

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "displayName",
            "value": "My Admins 123"
        }
    ]
}

Response Example

{
    "id": "SCGRospWarMpa73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins 123",
    "externalId": "custom_id",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": []
}

Delete / Deprovision Group

Remove a group in Tonkean.

DELETE: {BASE_URL}/Groups/{TonkeanGroupID} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRospWarMpa73)

Authorization: Bearer {ACCESS_TOKEN}

Request Example

—

Response Example

204 No Content

Get Groups

Get existing groups in Tonkean.

GET: {BASE_URL}/Groups/

Authorization: Bearer {ACCESS_TOKEN}

Query Params:

Param Name

Default

Description

startIndex

1

Index to start listing users from.

count

100

Amount of items to return in the call.

filter

—

Only supported filter: displayName.

Request Example

—

Response Example

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 3,
    "startIndex": 1,
    "itemsPerPage": 100,
    "Resources": [
        {...},
        {...},
    ]
}

Get Group by Tonkean ID

Get user details in Tonkean based on tonkean Id (for example, SCGRxxxyyyzzz).

GET: {BASE_URL}/Groups/{TonkeanUserID} (for example, https://api.tonkean.com/scim/v2/Groups/SCGRCmyuSxtya73)

Authorization: Bearer {ACCESS_TOKEN}

Request Example

—

Response Example

{
    "id": "SCGRCmyuSxtya73",
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
    ],
    "displayName": "My Admins 111",
    "externalId": "custom_id 111",
    "meta": {
        "resourceType": "Group"
    },
    "projectId": "PROJlYbHeXURWb2",
    "members": []
}
In this section: