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
- Endpoints
- Complete User Creation Flow Example
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"
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 enpoint 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",
"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"
}
}
HTTP/1.1 204 No Content
Note, only the following attributes are now supported:
- sendInvite
- managerEmail
- isAdmin
- license
- teams
- isActive
Disable a user
{
"schemas":[
"urn:ietf:params:scim:schemas:totango:1.0:User"
],
"active": false
}
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
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}
Comments
0 comments
Article is closed for comments.