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.
Over the SCIM API, Talkdesk receives the user’s first name, last name and e-mail 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.
Prior to initiating the configuration, please ensure the necessary credentials to provide the service are available (OAuth 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 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.
Creating the SCIM Application in OKTA
1. Log in and go to Applications [1] > Applications [2] > Browse App Catalog [3].
2. Search for SCIM 2.0 Test App (OAuth Bearer Token) and click “Add”.
3. Give the application a name (i.e. “SCIM 2.0 Test App”) [4] and deselect any options [5]; default values should be ok.
4. Click Next [6].
5. On “Sign on methods”, select SAML 2.0 [7].
6. In the “Application username format” field under “Credentials Details”, select Email [8] and click Save [9].
Configuring the Provisioning
1. Enter the application we created in the first step in Applications > Applications > SCIM 2.0 Test App.
2. Go to the Provisioning tab [1] and click on Configure API Integration [2].
3. Tick the option “Enable API integration” [3].
4. Enter https://api.talkdeskapp.com/scim/v2 on the “SCIM 2.0 Base Url” field [4].
5. Then, type in the bearer-generated token in the “OAuth Bearer Token” field [5]. If you need more information about how to generate an OAuth Token, please visit this article.
6. Click on Test API Credentials [6] to ensure it works, and click on Save [7].
7. On the left-hand side menu, go to Settings > To App [8] and click “Edit”. Then, tick the “Enable” flags in “Create Users” [9], “Update User Attributes” [10], and “Deactivate Users” [11]. Save the changes [12].
8. Scroll down on the same page and ensure the above fields are in the mappings.
Alternatively, if you want to assign the role or the team to the user during the SCIM Provisioning, click on the option Go to Profile Editor [13], click on “+ Add Attribute”, and enter the following information:
Role:
- Data type: string
- Display name: rolesString
- Variable name: rolesString
- External name: rolesString
- External namespace: urn:ietf:params:scim:schemas:extension:talkdesk:2.0:User
- Enum: unchecked
- Required: unchecked
- Scope: unchecked
- Mutability: READ_WRITE
Note: If the Role field is empty, Talkdesk will create the user with the default Role Agent.
Team:
- Data type: string
- Display name: teamsString
- Variable name: teamsString
- External name: teamsString
- External namespace: urn:ietf:params:scim:schemas:extension:talkdesk:2.0:User
- Enum: unchecked
- Required: unchecked
- Scope: unchecked
- Mutability: READ_WRITE
9. Finally, go to Assignments [14], click on the People section [15], and use the search field to select the people or groups to be provisioned in SCIM.
How to Get Access to the SCIM API
Setup and enablement are conducted by Talkdesk. Please reach out to us if you wish to use this feature.
Token Renewal
Talkdesk SCIM API offers out-of-the-box integration with Okta.
For SCIM API, the default token duration for the SCIM API OAuth client is 30 days. This means you will have to renew the token every 30 days. For more information, refer to Authentication.