With the Totango API, you can manage Totango system users from your system via API. The API allows you to create new users, update existing user 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 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

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

Within your own user profile, copy the API token key on the Integrations 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"

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

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"

Token must belong to a user with global admin privileges in Totango.

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.

In case these attributes do not appear in the Create User API, default values are in use. These are the system defaults for Totango user attributes:

• License - The user license that defines the access to Totango products. Please note that the values for Practitioner and Contributor licenses must be named "Spark" and "Zoe," respectively. 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, the user will be assigned to the default team defined in Totango. 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"

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 

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": "replace",
      "value": {
        "active": false
      }
    }
  ]
}

HTTP/1.1 204 No Content 

Replace User

Invoke the Users endpoint 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

{
    "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

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

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

curl -X POST \
  'https://app.totango.com/t01/on/oauth2/api/v1/token?grant_type=client_credentials' \
  -H 'Authorization: Basic dGVzdGluZy51c2VyKzIzNV9hZG1pbkB0b3RhbmdvLmNvbTpUZXN0aW5nVXNlcjEyMzQ='

HTTP/1.1 200 OK

{
  "access_token" : "607d378d7f794b3f1cdb525ec694687239f5e5a2",
  "token_type" : "Bearer",
  "expires_in" : 86400,
  "scope" : ""
}

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",   
    }
}'

{
    "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"
    }
}

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
• Enable Global Admin creation via SCIM API: Enable/Disable operations with Global Admin users via SCIM API. SCIM base URL is given for your service.
• 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.
• Keep team assignment when replacing a user without team assignment data: If enabled, keep the current team assignment and admin status when replacing a user w/o team assignment or admin flag to avoid a situation that there is no team assignment and user loose admin permissions.

Contact Totango Support to join the SCIM beta and to enable Totango UUID.

Totango UUID (Beta)

Totango UUID is using a UUID for each Totango user which is different from the user email. This allows Totango admin to change users emails without affecting the user.

Use cases:

• Totango user email is changed due to name change (marriage, or other reason)
• Company name is changed and Totango users emails are changed accordingly
• Company is acquired and Totango users emails are changed accordingly

Please contact Totango Support to join the SCIM beta and to enable Totango UUID.

Swagger documentation

Swagger documentation could be found at this link