SCIM API

Overview

SCIM 2.0, the System for Cross-domain Identity Management standard, allows for user identity information management between cloud systems. Talkdesk® enables automatic and simplified user management through the SCIM 2.0 protocol. Our SCIM API follows this protocol so please refer to the IETF standard Core Schema RFC and to the Protocol RFC to learn more.

Over the SCIM API, Talkdesk receives the user’s first name, last name and email information and creates the user based on it. By default, the user status is “active”, which means that the licensing is automatically consumed on provisioning.

🚧

Pre-requisites

Prior to initiating the configuration, please ensure the necessary credentials to provide the service are available (STS token), and that enough licenses exist at Talkdesk for all the users.

If at the end of the procedure, some users are provisioned with the “Deactivated” status in the Talkdesk system, it may be due to the lack of licenses for all new users. In this case, please check the complete information in Agents and Licenses.

📘

Notes

The SCIM API only supports the User resource.

The SCIM API does not work for Talkdesk Phone user creation.

The rate limit for this API is 4 requests per second, if you encounter a 429 response status code (Too many requests), please retry within the next second.

STS tokens

STS tokens can live forever as long as they are being used. For more information, refer to Client Credentials - STS.

📘

Create a new STS token

Follow these steps to create a new STS token:

• Make a single POST request to: https://.talkdeskid.com/oauth/token
  • The base URL (i.e. talkdeskid.com) is determined by your account instance's region. To view the available options, please check the following page: Client Credentials - STS
• Use Basic Authentication with:
  • Username: Your OAuth client ID
  • Password: Your OAuth client secret
• The request body should include the following fields:
  • grant_type=client_credentials
  • token_type=opaque
  • expires_in=31556952 (token lifetime in seconds)
  • scope=scim

Basic Authentication Format

The Basic Authentication header requires a Base64 value:

• Combine client ID and secret as: clientId:clientSecret
• Encode this string with Base64
• Add header: Authorization: Basic <encoded-string> - replace <encoded-string> with the Base64 value

Command line example

ShellPowerShell

basic_auth=$(echo -n 'clientId:clientsecret' | base64)

curl --location 'https://<account-name>.talkdeskid.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic $basic_auth" \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=scim' \
--data-urlencode 'token_type=opaque' \
--data-urlencode 'expires_in=31556952'

$basic_auth = [Convert]::ToBase64String([char[]]'clientId:clientSecret')

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/x-www-form-urlencoded")
$headers.Add("Authorization", "Basic $basic_auth")

$body = "grant_type=client_credentials&token_type=opaque&scope=scim&expires_in=31556952"

$response = Invoke-RestMethod 'https://<account-name>.talkdeskid.com/oauth/token' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

Integration with different systems

Talkdesk offers integration with:

• OKTA
• Microsoft Entra ID
• OneLogin

Besides these integrations, it's also possible to create a custom integration by using our available SCIM API endpoints.

📘

SCIM Integration

• OKTA
• Microsoft Entra ID
• OneLogin
• Custom integration

Note that only the supported fields should be configured to be sent to the Talkdesk SCIM API, otherwise the integration might fail. The list of supported fields can be found here.

Troubleshooting

If you have questions or technical issues, please open a ticket using this form.