Who can use this feature?
- Global admins or users with advanced permissions
- Available on all plans
OAuth is an open standard for access delegation, commonly used as a way for users to grant websites or applications access to their information on other websites but without giving them the passwords.
Totango leverages the OAuth protocol to allow developers to write third-party applications that interact with Totango using secured API calls. You can then register these applications in Totango to ensure secured connectivity.
Understand key concepts
This section explains the key concepts that administrators should take into consideration when designing and maintaining third-party applications for registration with Totango.
Scopes
Scope is the OAuth equivalent of permissions. Each Totango API declares the scope(s) that are required to invoke it. The application’s developer is responsible for keeping track of the set of scopes that are required by the application, so they can be configured when the application is registered in Totango.
Supported grant types
The OAuth standard defines several grant types for different use cases. Totango supports the following types:
- Authorization Code: For applications that access Totango on behalf of end users. When a user accesses the application for the first time, they’ll be redirected to the Totango application so they can grant permission to the application to access Totango on their behalf.
- Client Credentials: For applications that access Totango directly (sometimes referred to as Machine-To-Machine). You’ll need to select a user that the application will use, since Totango API requires a user identity for most operations.
Register an OAuth application in Totango
Totango limits the number of applications you can create to two. Contact your Totango representative if you need additional applications.
- From the left nav, click Settings > OAuth Applications.
- Click the + Create new application button.
- On the Register New OAuth Application screen, enter the following details:
- Application name: For display purpose within Totango.
- Access Token Expiration: Default is 24 hours, which is the maximum value. If your security requirements are more strict, you can specify a shorter expiration period.
-
Grant type: Choose from the following:
- Authorization Code: Specify one or more Authorization Callback URLs of your application, which are used during the authorization flow. (Totango redirects to the specified callback URL.)
- Client Credentials: Select a user that the application will use. Note that if this user is disabled or deleted, the application will not be able to access Totango.
- Scopes: Determine the level of access the OAuth token will have to your data in Totango. Select the scopes required by your application. (See below.)
- Click Create Application.
A success message appears with the properties of your OAuth application, including the Client ID and Client Secret, which you should copy into your application’s configuration. - Click Close.
For security considerations Totango stores the Client Secret as a password, to ensure it cannot be leaked. Make sure you store it securely, as it cannot be restored.
View and update application details
From the OAuth Applications list, you can click an application to view its details. In the details page you can:
- Update the access token expiration
- For applications with an authorized code grant type:
- Modify the list of authorization callback URLs
- Delete the application: This will also revoke all access tokens granted to the application, as well as the application certificate (if certificate binding is enabled)
For Developers
The following information is for developers designing and implementing third-party applications using Totango APIs using OAuth
Configuration
In addition to the client id and client secret provided during registration, you’ll need to configure the Totango OAuth endpoints in your application’s OAuth library:
-
Authorization: /oauth/authorize
- (Required only for Authorization Code grant type)
- Token: /oauth/token
Note that the endpoint should be prefixed with a base url according to the region your account belongs to:
-
US:
https://api-gw-us.totango.com
-
EU:
https://api-gw-eu1.totango.com
Scopes
Scopes are organized based on entities (e.g., accounts, users) and operations (e.g., read, update) according to the following patterns. This structure allows you to either provide fine-grained access to specific operations, or to use the :all scope to simplify and shorten the scopes list.
- {entity}:all - Has access for all operations and scopes in the entity
- {entity}:read - Has access to fetch data
- {entity}:create - Has access to create data
- {entity}:update - Has access to update data
-
{entity}:upsert - Has access to create and update data
- Combines update & create scopes
- Some entities do not have different APIs for create & update
-
{entity}:delete - Has access to delete data
- Some entities do not have this API
- {entity}:definitions:read - Has access to read definitions (e.g., attributes)
- {entity}:definitions:upsert - Has access to update definitions (e.g., attributes)
-
{admin} - Has access to all scopes
- Use with caution. This is useful during the development phase, but is usually considered a security anti-pattern in production systems.
Totango APIs
The following table lists the supported APIs and their corresponding scopes. Make sure to add the prefix according to your region, as described in the configuration section above.
US: https://api-gw-us.totango.com/api/v3/touchpoint-types
EU: https://api-gw-eu1.totango.com/api/v3/touchpoint-types
US: https://api-gw-us.totango.com/int-hub/api/v1/accounts
EU: https://api-gw-eu1.totango.com/int-hub-eu1.totango.com/api/v1/accounts
API Endpoint | Required Scopes | |
POST /int-hub/api/v1/accounts ➜ Documentation: Update accounts |
account:upsert | |
POST /int-hub/api/v1/accounts/attributes ➜ Documentation: Update account attribute definitions |
account:definitions:upsert | |
POST /int-hub/api/v1/accounts/users ➜ Documentation: Update users |
user:upsert | |
POST /int-hub/api/v1/accounts/users/attributes ➜ Documentation: Update user attribute definitions |
user:definitions:upsert | |
POST /int-hub/api/v1/collections/{collection_type} ➜ Documentation: Update collections |
collection:upsert | |
POST /int-hub/api/v1/collections/{collection_type}/attributes ➜ Documentation: Update collection attribute definitions |
collection:definitions:upsert | |
GET /int-hub/api/v1/status/{batchId} ➜ Documentation: Attributes records processing status by batch ID |
||
POST /api/v1/search/accounts ➜ Documentation: Search API |
account:read | |
POST /api/v1/search/users ➜ Documentation: Search API |
user:read | |
POST /api/v1/search/accounts/collections ➜ Documentation: None |
collection:read | |
GET /api/v1/users/whoami ➜ Documentation: None |
system_user:read | |
DELETE /api/v2/users/account-user/{account-id}/{user-id} ➜ Documentation: User delete API |
user:delete | |
GET /api/v2/events ➜ Documentation: Retrieve events per account |
event:read | |
POST /api/v2/events/search ➜ Documentation: Event search API |
event:read | |
GET /api/v2/audit ➜ Documentation: Audit Log API |
system_user:read | |
GET /api/v2/scim/services/{service-id}/Users ➜ Documentation: SCIM Get Users |
system_user:read | |
GET /api/v2/scim/services/{service-id}/Groups ➜ Documentation: SCIM Get groups/teams |
system_user:read | |
POST /api/v2/scim/services/{service-id}/Users ➜ Documentation: SCIM Create user |
system_user:create | |
GET /api/v2/scim/services/{service-id}/Users/{user-id} ➜ Documentation: SCIM Get users |
system_user:read | |
PATCH /api/v2/scim/services/{service-id}/Users/{user-id} ➜ Documentation: SCIM Update user |
system_user:update | |
PUT /api/v2/scim/services/{service-id}/Users/{user-id} ➜ Documentation: SCIM Replace user |
system_user:update | |
GET /api/v2/scim/services/{service-id}/Groups/{team-id} ➜ Documentation: SCIM Get groups / teams |
system_user:read | |
PUT /api/v2/scim/services/{service-id}/Groups/{team-id} ➜ Documentation: SCIM Set users for group / team |
system_user:update | |
PATCH /api/v2/scim/services/{service-id}/Groups/{team-id} ➜ Documentation: SCIM Add users to Group / Team |
system_user:update | |
GET /api/v2/teams/{team-id} ➜ Documentation: Get team detail |
||
POST /api/v2/automations/run-manual-successplay ➜ Documentation: Run manual SuccessPlay |
||
GET /api/v3/objective-settings/status ➜ Documentation: Get objective status |
||
GET /api/v3/objective-settings/category ➜ Documentation: Get objective category |
||
POST /api/v3/objectives ➜ Documentation: Create an objective |
||
PUT /api/v3/objectives/{objective-instance-id} ➜ Documentation: Update an objective |
||
DELETE /api/v3/objectives/{objective-instance-id} ➜ Documentation: Delete an objective |
||
GET /api/v3/objective-templates ➜ Documentation: Get objective template ids |
||
POST /api/v3/objective-templates ➜ Documentation: Create objective from objective template library |
||
GET /api/v3/accounts/{account-id}/plan_summary ➜ Documentation: Get account plan summary |
||
GET /api/v3/OSPData/{SBID}?accountsID[]={account-id} ➜ Documentation: Outcome success plan report (API) |
||
POST /api/v3/tasks ➜ Documentation: Create a new task |
task:create | |
Put /api/v3/tasks/{task-id} ➜ Documentation: Update a task |
task:update | |
DELETE /api/v3/tasks/{task-id} ➜ Documentation: Delete a task |
task:delete | |
POST /api/v3/touchpoints ➜ Documentation: Create a new touchpoint |
touchpoint:create | |
PUT /api/v3/touchpoints/{note-id} ➜ Documentation: Update an existing touchpoint |
touchpoint:update | |
DELETE /api/v3/touchpoints/{note-id} ➜ Documentation: Remove a touchpoint |
touchpoint:delete | |
GET /api/v3/touchpoint-types ➜ Documentation: Retrieve a list of touchpoint types |
touchpoint:definitions:read | |
GET /api/v3/touchpoint-tags ➜ Documentation: Retrieve a list of touchpoint reasons |
touchpoint:definitions:read | |
GET /api/v3/activity-types ➜ Documentation: Retrieve a list of flow IDs |
touchpoint:definitions:read |