Manage Your Totango System Users Remotely Using API

Who can use this feature?

Global admins
Available on all plans

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

Enable SCIM integration and get a personal access token

Any interaction with the SCIM API must include an authentication token. The actual SCIM API is identical, no matter which token is being used.

From Settings, expand User Management > Totango Users > General Settings.
Select the option to Enable SCIM APIs for User Management.
Choose from the following additional settings:
- 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.
  When set to Yes, you can manage your Totango users with user management APIs or Totango application UI only, and you cannot 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 lose admin permissions.
Exit Settings.
From the right corner of the main Totango page, click your profile > Edit Profile.
From the Integrations tab, create a new token and copy it.
Click Close.

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 User by ID

 curl --location --request GET <Base URL>/Users/<userID> \
-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"

Get Group / Team by ID

 curl --location --request GET <Base URL>/Groups/<teamID> \
-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"
}

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": <User 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": <User 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

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

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

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}

Important notes

Enable SCIM integration and get a personal access token

Using the App-Token

Getting a standard OAuth token

Using the OAuth token

Get Users

Filter Users

Get User by ID

Get Groups / Teams

Get Group / Team by ID

Create User

user.json

Mandatory Totango user attributes

Create user success response

Create user error response

Update User

user_update.json

Disable a user

Replace User

user_replace.json

Response

Set Users for Group / Team

group.json

Response when successful

Add users to Group / Team

new_team_members.json

Response when successful

Remove users from Group / Team

remove_team_members.json

Response when successful

Endpoints

Complete user creation flow example

Get bearer token

Response

Create user

Response when successful

When the user already exists

Was this article helpful?

In this article

<%= heading %>

<% if (block.html_url) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Categories

Toggle navigation menu

<%= category.name %>

Categories

Categories