Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Totango User Lifecycle API SCIM support

SCIM API

Supported Lifecycle operations

Single User operations only are supported (no bulk)

Endpoints

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 parameters

STD & 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 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}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.