Manage Your Totango System Users Remotely Using API

Product Team
  • Updated

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, replace a user, and delete user. 

Important notes:


This article includes the following topics

 

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"    
  },
  "urn:ietf:params:scim:schemas:totango:1.0:User": {
    "isActive" : true,
    "license": ["zoe"],
    "isAdmin": false,
    "managerEmail": "tracyd@work.com",
    "managerExternalId": "optional",
    "teams": [
      {"name": "first team"},
      {"name": "second team"}
    ]
  }
}
  • Custom totango schema notation is defined as per spec here
  • Custom totango schema is defined as per spec here

 

Create 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 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

{ 
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "Operations":[
    {
      "op":"replace",
      "value":[
        {
          "title": "CSM Director",
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "license" : ["zoe","spark"]
          }
        }
      ]
    }
  ]
}
HTTP/1.1 204 No Content

 

Deactivate a user 

{ 
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations":[
    {
      "op":"replace",
      "value":[
        {
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "isActive" : 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:PutOp",
    "urn:ietf:params:scim:schemas:totango:1.0:User"
  ],
  "Operations": [
    {
      "op": "replace",
      "value": [
        {
          "name": {
            "familyName": "new_famiy22",
            "givenName": "new_name222"
          },
          "title": "Updated User Title",
          "urn:ietf:params:scim:schemas:totango:1.0:User": {
            "license": [
              "zoe"
            ],
            "teams": [
              {
                "name": "Team_for_SCIM_tests"
              }
            ]
          }
        }
      ]
    }
  ]
}

Response

HTTP/1.1 204 No Content

 

Endpoints

The SCIM interactions involve two endpoints

  • OAuth: https://{env}.totango.com/oauth2/api/v1/token
  • SCIM: https://{env}.totango.com/api/v2/scim/services/{service-id}/Users/{user-id}

Env: as appears in the main totango application URL
ServiceID: customer (service) ID
UserID: user ID (email) on which we operate

 

Example Flow

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-test.totango.com/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-test.totango.com/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"
  },
  "urn:ietf:params:scim:schemas:totango:1.0:User": {
    "isActive" : true,
    "license": ["zoe"],
    "isAdmin": false,
    "managerEmail": "tracyd@work.com",
    "managerExternalId": "1234585",
    "teams": [
      {"name": "Team_for_SCIM_tests"}
    ]
  }
}'


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}

 

 

 

Related articles

Comments

0 comments

Article is closed for comments.

Articles in this section