Overview
Manage your Totango system users right from your system via API.
This API allows you to create new users, update existing users' information and access permissions, and replace a user. User deletion is not supported via this API.
Important notes:
- Authorization is supported via a proprietary Totango App-Token or a standard OAuth token.
- The token must belong to a user with Global Totango Admin privileges.
- The API adheres to the SCIM (System for Cross-domain Identity Management) specification.
- SSO enforcement in your instance login is intended for Totango Application user log-in, and has no effect on this API which is in the context of the server to server interaction.
This article includes the following topics
- Authorization Tokens
- Get Users
- Get Groups / Teams
- Create User
- Update User
- Disable User
- Replace User
- Set Users for Group / Team
- Add users to Group / Team
- Remove users from Group / Team
- Endpoints
- Complete User Creation Flow Example
- Swagger documentation
Authorization Tokens
Any interaction with the SCIM API must include an auth token. It can be either the proprietary Totango token or the standard OAuth one. The actual SCIM API is identical - no matter which token is being used.
Getting a Totango App-Token
Found in the application user’s profile, integration tab
Using the App-Token
Verb <Base URL>/Users body -H "app-token: <above-api-token>" \
-H "Content-Type: application/json"
Getting a standard OAuth token
POST '<Base URL>/oauth2/api/v1/token?grant_type=client_credentials' \
-H 'Authorization: Basic <base64 of user@work.com:password>'
>> 200 OK
{
"Access_token" : "607d378d7f794b3f1cdb525ec694687239f5e5a2",
"token_type" : "Bearer",
"Expires_in" : 86400,
"Scope" : ""
}
Using the OAuth token
Verb <Base URL>/Users body -H "Authorization: Bearer <AboveAccessToken>" \
-H "Content-Type: application/scim+json"
Once an auth token is obtained, we can continue with the operations as described below.
Important note, the examples in this article uses the OAuth header, to use the Totango App-Token, refer to the example above.
Get Users
curl --location --request GET <Base URL>/Users \
-H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
Filter Users
curl --location --request GET <Base URL>/Users?filter=<field name> eq <field value> \
-H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
Fields available for search:
- userName (email)
- externalId
Important: filter works only for one field, you can not combine two filters
Get Groups / Teams
curl --location --request GET <Base URL>/Groups \
-H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
Create User
$ curl -XPOST <Base URL>/Users -d @user.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
Important:token must belong to a user with Global Totango Admin privileges
user.json
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"userName": "ericd@company.com unique, not null",
"externalId": "701984 - optional, will be returned as-is by totango",
"title": "CSM Team Leader",
"displayName": "Eric Dunn",
"name": {
"familyName": "Dunn",
"givenName": "Eric"
},
"groups": [
{
"value": "2694",
"$ref": "../Groups/2694",
"display": "Global Team",
"teamrole": "Team Admin"
}
],
"urn:ietf:params:scim:schemas:totango:1.0:User": {
"isActive" : true,
"license": ["zoe"],
"isAdmin": false,
"managerEmail": "tracyd@work.com",
"managerExternalId": "optional",
]
}
}
- Custom Totango schema notation is defined as per spec here
- Custom Totango schema is defined as per spec here
Mandatory Totango user attributes
When creating a Totango user there is mandatory information that has to be sent in order to create the user.
These are the mandatory Totango user attributes:
- userName - the Totango user unique identifier which must be an email. Email addresses are limited to 100 chars.
- givenName - the user's first name for displaying it across Totango products and communications. This information is mapped to the first name attribute of the Totango user object and it is limited to 30 chars
- familyName - the user's last name for displaying it across Totango products and communications. This information is mapped to the last name attribute of the Totango user object and it is limited to 30 chars.
These are the system defaults for Totango user attributes:
In case these attributes do not appear in the Create User API default values are in use. These are the attributes and the default values which will be used:
- License - the user license which defines the access to Totango products. The value can be "Spark" or "Zoe". The default value is "Spark".
- externalId: empty, no default value. limited to 128 chars.
- title: empty, no default value. limited to 128 chars.
- displayName: the default value is a concatenate of the last name and first name as appear in this API. limited to 128 chars.
- isActive: empty, there is no default value. A user will be considered as an active user if he logged into Totango products at least once. Valid values: "yes", "no","true", "false".
- isAdmin: the default value is "false"
- managerEmail: empty, no default value. limited to 100 chars.
- managerExternalId: empty, no default value. limited to 128 chars.
- groups: in case a user has no team, he will be assigned to the default team defined in Totango Spark. limited to 128 chars.
Create user success response
As per spec
HTTP/1.1 201 Created
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"meta": {
"created": "2019-05-02T10:58:54Z",
"resourceType": "User"
},
"userName": "ericd@company.com",
}
Create user error response
As per spec
HTTP/1.1 409 Conflict
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"uniqueness"
"detail":"user already exists",
"status": "409"
}
Or
HTTP/1.1 400 Bad Request
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"scimType":"invalidValue"
"detail":"userName must be an email",
"status": "400"
}
Update User
Invoke the Users endpoint with the UserID and a PATCH verb, see spec for full details.
Parameters sent will override existing ones, existing User attributes which were not updated will remain unchanged.
$ curl -XPATCH <Base URL>/Users/userID -d @user_update.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
Update Standard & Custom Properties
user_update.json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "title",
"value": "Senior Success Manager"
}
]
}
HTTP/1.1 204 No Content
Note, only the following attributes are now supported:
- userName *
- name.familyName
- name.givenName *
- name
- externalId
- title
- managerEmail
- managerExternalId
- active
- license
- groups *
* - the attribute can not be removed or set to empty value
Disable a user
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "title",
"value": "Senior Success Manager"
}
]
}
HTTP/1.1 204 No Content
Replace User
Invoke the Users enpoint with the UserID and a PUT verb, see spec for full details.
Parameters sent will override existing ones, existing User attributes which were not sent will be deleted.
curl -XPUT <Base URL>/Users/userID -d @user_replace.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
user_replace.json
{
"schemas":[
"urn:ietf:params:scim:api:messages:2.0:PatchOp",
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"userName":"ericd@company.com unique, not null",
"externalId":"701984",
"title":"CSM Team Leader",
"displayName":"Eric Dunn",
"name":{
"familyName":"Dunn",
"givenName":"Eric"
},
"active": true,
"groups":[
{
"value":"2694",
"$ref":"../Groups/2694",
"display":"Global Team",
"teamrole":"Team Admin"
}
],
"urn:ietf:params:scim:schemas:totango:1.0:User":{
"isActive":true,
"license":[
"zoe"
],
"isAdmin":false,
"managerEmail":"tracyd@work.com",
"managerExternalId":"optional"
}
}
Response
HTTP/1.1 204 No Content
Set Users for Group / Team
$ curl -XPUT <Base URL>/Groups/<Team Id> -d @group.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
group.json
{
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": <Team ID>,
"displayName":"scimTestTeam1",
"members":[
{
"value": <Usear ID>,
}
],
"meta":{
"resourceType":"Group",
"location":"<Base Url>/<Service ID>/Groups/<Team ID>"
}
}
Response
When successful
HTTP/1.1 200 OK
{
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"id": <Team ID>,
"displayName":"scimTestTeam1",
"members":[
{
"value": <Usear ID>,
}
],
"meta":{
"resourceType":"Group",
"location":"<Base Url>/<Service ID>/Groups/<Team ID>"
}
}
Add users to Group / Team
$ curl -XPATCH <Base URL>/Groups/<Team Id> -d @new_team_members.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
new_team_members.json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": <User ID>
}
]
}
]
}
Response
When successful
HTTP/1.1 200 OK
Remove users from Group / Team
$ curl -XPATCH <Base URL>/Groups/<Team Id> -d @remove_team_members.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"
remove_team_members.json
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "remove",
"path": "members",
"value": [
{
"value": <User ID>
}
]
}
]
}
Response
When successful
HTTP/1.1 200 OK
Endpoints
The SCIM interactions involve two endpoints
- OAuth: https://app.totango.com/{site}/{domain}/oauth2/api/v1/token
- SCIM: https://app.totango.com/{site}/{domain}/api/v2/scim/services/{service-id}/Users/{user-id}
Site: as appears in the main Totango application URL (t11 or t01)
Domain: as appears in the main Totango application URL
ServiceID: customer (service) ID
UserID: user ID (email) on which we operate
Note: when using the Totango App-Token, there is no use of the OAuth endpoint.
Complete User Creation Flow Example
A complete flow example of getting the Auth token and using it in the SCIM API
Get Bearer token
Invoke token endpoint with base64 encoded credentials
Credentials must be in the username:password
format, for example: joe.green@work.com:passWord123
Important: token must belong to a user with Global Totango Admin privileges
curl -X POST \
'https://app.totango.com/t01/on/oauth2/api/v1/token?grant_type=client_credentials' \
-H 'Authorization: Basic dGVzdGluZy51c2VyKzIzNV9hZG1pbkB0b3RhbmdvLmNvbTpUZXN0aW5nVXNlcjEyMzQ='
Response
HTTP/1.1 200 OK
{
"access_token" : "607d378d7f794b3f1cdb525ec694687239f5e5a2",
"token_type" : "Bearer",
"expires_in" : 86400,
"scope" : ""
}
Create User
Use above access_token in the Bearer Header
curl -X POST \
https://app.totango.com/t01/on/api/v2/scim/services/235/Users \
-H 'Authorization: Bearer 607d378d7f794b3f1cdb525ec694687239f5e5a2' \
-H 'Content-Type: application/scim+json' \
-d '{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"userName": "e2e_user023@totango.com",
"externalId": "701984",
"title": "CSM Team Leader",
"displayName": "E2e User",
"name": {
"familyName": "E2E",
"givenName": "User"
},
"groups": [
{
"value": "2694",
"$ref": "../Groups/2694",
"display": "Global Team",
"teamrole": "Team Admin"
}
]
"urn:ietf:params:scim:schemas:totango:1.0:User": {
"isActive" : true,
"license": ["zoe"],
"isAdmin": false,
"managerEmail": "tracyd@work.com",
"managerExternalId": "1234585",
}
}'
Response
When successful
HTTP/1.1 201 Created
{
"url": "https://app-test.totango.com/api/v2/scim/services/235/Users",
"reason": "Created",
"status_code": 201,
"json": {
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"meta": {
"created": "2019-07-31T01:10:01.564Z",
"resourceType": "User"
},
"userName": "e2e_user_ttwvr@company.com"
}
}
When the user already exists
HTTP/1.1 409 Conflict
{"schemas":["urn:ietf:params:scim:api:messages:2.0:Error"],"scimType":"uniqueness","detail":"user already exists","status":409}
SCIM User Settings (Beta)
SCIM API Settings available to be enabled for service in Global Settings > User Management > Totango Users > General Settings > Enable SCIM User APIs and includes the next parameters:
- Enable SCIM APIs for User Management - Enable/Disable SCIM API for User Management in the Service
- Use UUID as User's identifier - Enable/Disable using email as the main key for users
- Enable Global Admin creation via SCIM API - Enable/Disable operations with Global Admin users via SCIM API
- Validate External ID Uniqueness - Enable/Disable validation for the uniqueness of external id on creating and editing users via SCIM API. Note: When set to ‘Yes’, you can manage your Totango users using user management APIs or Totango application UI only and you can not use Customer Data Hub to manage your Totango users.
Please contact Totango Support to join the SCIM beta
Swagger documentation
Swagger documentation could be found at this link
Comments
0 comments
Please sign in to leave a comment.