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

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

$ curl -XPATCH <Base URL>/Groups/<Team Id> -d @remove_team_members.json -H "Authorization: Bearer <AuthToken>" -H "Content-Type: application/scim+json"

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:PatchOp"
    ],
    "Operations": [
        {
            "op": "remove",
            "path": "members",
            "value": [
                {
                    "value": <User ID>
                }
             ]
        }
    ]
}

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

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}