Tangoe Procurement for Rivermine and Command [MobProc]

Authentication

Users must be authenticated in order to use this API. This authentication is performed using the OAuth 2, the accepted industry standard for API security. Specifically, Tangoe currently supports the following two user credential OAuth grant types:

• Resource Owner Password Credentials
• Implicit

Below are descriptions of the uses cases for which each type is recommended. If you have a use case that you think would be better served by another grant type, please contact your Tangoe representative.

Grant Type: Resource Owner Password Credentials

This grant type requires a valid username and password that is sent with each API call. It is only recommended when the communication is server-to-server, that is when both sides of the transaction use an encrypted, private data store for these credentials. Generally speaking, in this use case there is no user interface controlling the API call into which a human can enter a password. An example of this would be a Tangoe client who subscribes to the Command platform and is calling this API directly from the Tangoe Mobility (ServiceNow) app using a service account. Please note that any service account used must be authorized to act up behalf of your logged-in end user.

Grant Type: Implicit

In cases where the end user needs to manually enter their password. For example, if a user is accessing the API directly from a device that does not have any secure storage (e.g., using the Developer Portal or an app on a Smartphone). For this case we offer the implicit grant type.

Please note that the when using the implicit grant type, your end user’s login credentials are not stored for the duration of the user’s session, only the token is stored. This allows for a trusted third-party to evaluate the credentials and authenticate the user without the hosting app have any access to those credentials. A popular example of this grant type in action would be an application that allows a user to authenticate with their Facebook username/password. The login popup is provided by Facebook rather than the application itself and as a result the hosting application never has access to these credentials. In the case of Tangoe’s implicit OAuth 2, the Tangoe user store would act in the Facebook role.

Using the Access Token

Both grant types require a two-step process:

1. A request must be made to a unique authentication URL to obtain an access token. Please contact your Tangoe representative for that URL.
2. The consuming application must then pass that access token with every API call.

The access token for this API expires after one hour. However, when the access token is provided, Tangoe will also provide a refresh token. This refresh token can be passed with each call instead of the access token. Then, when the token is nearing expiration, a newly refreshed token will be automatically issued. In the case of the implicit grant type, this will save your end user the inconvenience of being repeatedly prompted to re-enter their username/password after an hour has passed. Refer to Access Tokens below for more information about how to request a token, refresh a token or validate a token.

Once you have obtained your access token, it will need to be passed in as a header with every request. Other required headers include your tenant code and your client ID. For example:

For more information regarding additional headers that may be passed, please refer to the Request Headers page.

Access Tokens

The MOBPROC REST API requires that users pass an access token with every API request.

An access token is obtained by making a request to a unique authentication URL. Please refer to the tutorial page entitled How to Request an Access Token (for Resource Owner Password Credentials grant type) for instructions how to do that.

The consuming application must then pass that access token with every API call. The access token for this API expires after one hour. However, when the access token is provided, Tangoe will also provide a refresh token. This refresh token can be passed with each call instead of the access token. Then, when the token is nearing expiration, a newly refreshed token will be automatically issued. In the case of the implicit grant type, this will save your end user the inconvenience of being repeatedly prompted to re-enter their username/password after an hour has passed. Please refer to the page entitled How to Refresh an Access Token for step-by-step instructions.

If you wish to determine whether your access token is currently valid and has not yet expired, please refer to the page entitled How to Validate an Access Token for specific instructions.

Tutorials for Managing Access Tokens

• How to Request an Access Token (for Resource Owner Password Credentials grant type)
• How to Refresh an Access Token
• How to Validate an Access Token

All of these tutorials tutorials are also available for download in one convenient PDF file (856 KB).

Request Headers

Request headers are simply just key/value pairs of metadata relating to what is contained within the body of a request and/or response. The Mobile Procurement API primarily uses them for identifying users and limiting context.

Video Tutorial

This video describes the custom headers that you can pass with any MOBPROC API request and how they are used.

We also recommend browsing all of our tutorials in our Video Library at http://mobproc.tv.

General Headers

General headers are added by the consumer of the API and are passed along to the appropriate backend system.

X-TNGO-TENANT

Used to identify the specific tenant for which the API is being called (i.e., the customer).

• Required
• Data type: string

client_id

Used to identify your client application as the one calling the API.

• Required
• Data type: string

Context ID Headers

Frequently the logged-in/authenticated user calling the API is a service account. However, service accounts do not specifically identify the actual end user who is placing the order, viewing assets, etc. The true end user (also known as “the actor”), must be identified by setting a context header. The API will use these identifiers to set the context for making the API call.

For example, imagine that an application called the API using a service account ID (i.e., admin.acme.com). Moreover, imagine that this request also included the X-TNGO-CONTEXT-COMPANYEMPLOYEEID header set to the company ID for an end user named Peter Edwards (i.e., pedwards.acme.com). When the request for the device catalog was executed, only devices that Peter Edwards was authorized to see would have been returned instead of the larger set of devices that the service account (admin.acme.com) was authorized to access.

X-TNGO-CONTEXT-COMPANYEMPLOYEEID

This is the employee ID assigned by the tenant/customer (e.g., employee’s email address, etc.). This header is only used when the X-TNGO-CONTEXT-EMPLOYEEID header is not set. If this header is NOT set, the context will be set to the authenticated user.

• Optional
• Data type: string

X-TNGO-CONTEXT-EMPLOYEEID

This is the employee ID assigned by Tangoe. If this header is set, it will be used in place of the X-TNGO-CONTEXT-COMPANYEMPLOYEEID header. If it is NOT set, then the X-TNGO-CONTEXT-COMPANYEMPLOYEEID header will be used (if set).

• Optional
• Data type: string

X-TNGO-CONTEXT-HIERARCHYID

The Tangoe-assigned ID that is used to specify the organizational hierarchy to be used for the API call. If this header is not set, the default hierarchy will be used.

• Optional
• Data type: string

Troubleshooting Headers

Troubleshooting headers are used to tag related and individual API calls, making it much easier to quickly locate their related activity in the server logs. All request and response activity that is logged for a single API call will be tagged with either/both of these headers, when they are set. Either header is useful, but they can be especially helpful when used together (with different values) to track a series of related API calls.

The X-TNGO-CONTEXT-ACTIVITYID header can be used to tag multiple related calls with the same identifier. Different identifiers can be used for the X-TNGO-CONTEXT-CORRELATIONID header in each individual API call within this related set to help us distinguish between each individual call. Having this ability to group related activity, while simultaneously maintaining the ability to tag the individual calls that comprise your grouping, can be really helpful to troubleshoot an error occurring within a complex multi-step process.

X-TNGO-CONTEXT-ACTIVITYID

Set this header with a value of your choice for multiple related API calls in order to sort them into a logical grouping.

• Optional
• Data type: string

X-TNGO-CONTEXT-CORRELATIONID

Set this header with a different unique value of your choice for each individual API call.

• Optional
• Data type: string

Metadata

In many places, this API’s responses include blocks of metadata relating to data points contained within that response. These supplementary blocks, which are always named “_meta,” typically contain fully-qualified URLs that resolve to other API calls for retrieving related detail data.

For example, the API call for a collection of employees might return items containing just a few selected details about each employee. However, each item also contains a “_meta” block populated with a URL that can be used to obtain that specific employee’s full detail record.

Video Tutorial

The following video provides a quick explanation of the “_meta” block included in most API responses — as well as explain what it typically includes.

We also recommend browsing all of our tutorials in our Video Library at http://mobproc.tv.

Detail Record Example

Metadata blocks make it very easy for the API consumer to easily obtain additional detail data for a selected item without having to bloat the collection by supplying those same details for every item returned within that collection.

This pattern is particularly useful for use cases such as a list page containing a “view details” button for every item in the list. The end user will likely want to scan a list and choose to find out more details about just one particular item, rather than view all the details of every item. Therefore, it is unnecessary to bloat the API response with a huge volume of detail that the end user is unlikely to want. Moreover, a smaller result set of more targeted data will enable the API to return results much faster.

Below is an illustration of a metadata block contained within a response for an employee collection.

{
  "_meta": {
    "href": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees/48068931",
    "hrefDevices": "https://tngo-mobproc.cloudhub.io/mobproc/v1/assets/devices?limit=10=0=48068931",
    "hrefServices": "https://tngo-mobproc.cloudhub.io/mobproc/v1/assets/services?limit=10=0=48068931"
  },
  "companyEmployeeId": "barbara.andrews@example.com",
  "department": {
    "id": "80022",
    "name": "Marketing"
  },
  "firstName": "Barbara",
  "id": "48068931",
  "lastName": "Andrews",
  "status": "ACTIVE"
},
{
  "_meta": {
    "href": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees/48068987",
    "hrefDevices": "https://tngo-mobproc.cloudhub.io/mobproc/v1/assets/devices?limit=10=0=48068987",
    "hrefServices": "https://tngo-mobproc.cloudhub.io/mobproc/v1/assets/services?limit=10=0=48068987"
  },
  "companyEmployeeId": "james.carpenter@example.com",
  "department": {
    "id": "80022",
    "name": "Marketing"
  },
  "firstName": "James",
  "id": "48068987",
  "lastName": "Carpenter",
  "status": "ACTIVE"
},
...

Pagination Data Example

Meta blocks are not limited to providing URLs for fetching detailed data. They can also hold data that is useful for supporting paginated lists, such as a total count or an items per page limit. For example:

"_meta": {
  "href": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?limit=10=30=true",
  "hrefEnd": "https://tngo--mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=70=10",
  "hrefNext": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=40=10",
  "hrefPrevious": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=20=10",
  "hrefStart": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=0=10",
  "limit": 10,
  "offset": 30,
  "totalCount": 72
}

Pagination

API calls for retrieving a collection of items frequently return large, unbounded result sets. In these cases, results are almost always paginated to improve performance and help the user more easily manage the handling of results.

Video Tutorial

This video explains how pagination works for selected API resources that are most likely to return very large, unbounded collections.

We also recommend browsing all of our tutorials in our Video Library at http://mobproc.tv.

Input Parameters

All paginated API calls require two input parameters: limit and offset.

The limit sets the maximum number of items to be included in single “page.” In other words, it is the number of items to be returned within the response, out of the total result set found by the query for that API call.

The limit value sets the maximum number of items to be included in the current page that gets returned from the total result set. The offset value identifies the index of the first item in that current page. For example, assume you have a result set of 50 items and you set the limit to 10 and the offset to 30. The result set would be grouped into 5 pages (50 / 10 = 5) and return the fourth page. (Indices 0 through 29 equals 30 items; 30 items divided by 10 equals 3 pages; so index 30 is the first item on the fourth page.)

Please note that the Premium Mobile source system (known by some as Command), implements the offset parameter a little differently. If you subscribe to that system, please refer to the note at the bottom of the page regarding the subtle difference in how the offset affects the results returned in the response.

Response Body

Paginated results always include a metadata block containing the details needed by the API consumer to navigate the result set. These details include:

• totalCount - The total number of items in the entire result set (i.e., across all pages).
• hrefStart - A fully-qualified URL for an API call that will return the FIRST page in the result set.
• hrefPrevious - A fully-qualified URL for an API call that will return the page that occurs immediately BEFORE the current page in the result set.
• hrefNext - A fully-qualified URL that will return the page that occurs immediately AFTER the current page in the result set.
• hrefEnd - A fully-qualified URL that will return the LAST page in the result set.

Each of these pagination position properties (i.e., hrefStart, hrefPrevious, hrefNext, hrefEnd) will be returned only when the link resolves to a page other than the current page. For example, say the offset is set to zero. The API response will return the first page in the result set. Therefore, the metadata will not include the hrefStart and hrefPrevious properties since they would both point to the same page as the one that is returned. This behavior is intended to make it easier for user interface logic to populate a pagination control. The logic can simply check for the absence of these properties to know when to disable navigation links.

Here is an example of what the pagination information in the metadata block might look like:

"_meta": {
  "href": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?limit=10=30=true",
  "hrefEnd": "https://tngo--mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=70=10",
  "hrefNext": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=40=10",
  "hrefPrevious": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=20=10",
  "hrefStart": "https://tngo-mobproc.cloudhub.io/mobproc/v1/employees?sortAscending=true=0=10",
  "limit": 10,
  "offset": 30,
  "totalCount": 72
}

A Note about Offset for Premium Mobile Users

API consumers who use Premium Mobile as their backend/source system should be advised that this system has implemented the offset parameter a little differently.

Prior to taking offset into account, Premium Mobile first calculates the pages based on the limit parameter only. For example, if the total result set is 28 items and the limit is 10, then three pages will be calculated. (Two with 10 items each, and one with eight.) Then, Premium Mobile will determine which of these pages includes the item represented by the index number passed in as the offset parameter. So, continuing with our example of 28 items in the result set, if the limit was three and our offset was set to 15, then the second page of results would be returned in the response and the offset item would not be the first item. This is because the item with the index number of 15 falls within the middle of the second page.

For other source systems, the behavior would be as described in the previous section. That is, the item represented by the index passed as the offset would be the first item in the results returned within the response.

Setting Context (“the Actor”)

Every API response must only include data that the authenticated user is authorized to view. Even when an API call is being made on the behalf of a different user, at no time should the API ever return data that the authenticated user is not authorized to see.

The one on whose behalf the API call is being made is considered the context for the API call. In the most simple case, this context is the authenticated user. However, sometimes it is desirable to change the user context. This is typically done for one of two reasons:

• Placing an order upon behalf of someone else. A common example of this could be when an administrative assistant places an order to upgrade a manager’s cellphone, using a procurement application that was configured to use this API. Even if the assistant who logged into the application was the authenticated user of the API, he or she placed the order for the benefit of their manager. Therefore, the context was changed to reflect that relationship. This is important for reasons including cases when a manager is authorized to choose from more cellphones in the device catalog than the assistant is authorized to order for their own use.
• Facilitating the use of a service account. For security reasons, your company may wish to restrict which accounts are authorized to make API calls to a single service account (and possibly a very limited number of administrator accounts). Although the service account is used to execute the API call, that call could have been originated by an employee using your company’s application. In this case, the order is being placed for the benefit of a particular end user and not the service account itself. The end user is the true context. For example, this would enable the API to return a smaller list from the device catalog that the end user is authorized to see, instead of the much larger list that the service account is authorized access (which could include all devices).

Whenever you need to change context, specific headers are used. Refer to the request headers section above for more information.

Employee ID vs. Company Employee ID

Before we can properly understand the difference between context and filtering, it is important to first know the difference between employee IDs and company employee IDs.

An employee ID is a GUID that is used to identify a specific employee and is generated by the Tangoe backend system (e.g., Premium Mobile). The company employee ID identifies this same employee, however the identifier is generated outside of the Tangoe backend system and can come in a variety of formats (e.g., number, email address, name, etc.). Although it is expected to be unique, Tangoe cannot guarantee its uniqueness since it is supplied by an external system. Therefore, the employee ID is always considered more reliable.

Whenever one of these identifiers is passed, either via headers or query parameters, it is important to know that the backend system will always check for the employee ID first. If one is NOT found, then the backend system will look to see if a company employee ID was passed and set the context to that. If neither was passed, then the backend system will set the context to the authenticated user.

Context

The default context of every API call is assumed to be the logged in user. Therefore, the API calls will only return data that this authenticated user has been authorized to access. Often this is the behavior that the user intended.

However, sometimes an API user may wish to execute a call on behalf of someone else. For example, an administrator might need to locate the device asset record in order to deactivate a phone that an employee has lost. In such case, the context of the API call is not the logged in user, but rather someone else whose data the administrator is authorized to access.

Changing the context is accomplished via adding a header to the request that is set to either a Tangoe-generated ID (i.e., employee ID) or a third-party-generated ID (i.e., company employee ID). Specifically, these two headers are:

• X-TNGO-CONTEXT-EMPLOYEEID
• X-TNGO-CONTEXT-COMPANYEMPLOYEEID

API resources that might require changing the context include:

• /catalog/devices
• /catalog/plans
• /catalog/accessories
• /regions
• /orders (HTTP POST method only)

/me

Sometimes it is helpful to retrieve additional details beyond the ID to identify the user to whom the context is set. The /me resource returns these details about the API caller and what they are able to procure. This information includes the identity of the authenticated user (i.e., logged-in user), as well as the identity of the user on whose behalf the API is being called (commonly known as “the actor”). If the authenticated user is not a service account, these two users will often be the same person. In addition, the response also includes a list of the order transaction types that the actor is authorized to perform.

Context vs. Filtering

As discussed above, we need to change the context of a call (sometimes referred to as “the actor”) when we are submitting it on behalf of another user. In other words, we wish to make the API call as if that other user was the one executing it. We also noted that we can only change the context to users that we are explicitly authorized to impersonate.

However, there is also the concept of filtering which is different than changing context. Filtering is when the default context is used (i.e., the authenticated user) but we wish to limit, or filter, the results so that only a subset is returned. For example, a manager may be authorized to see all of her devices, as well as all of the devices assigned to the employees in her department. However, when making the API call to the /assets/devices resource, she might wish to only see the devices assigned to just one of her employees. This case calls for use of the employee filter.

The employee filter is set via one of two following query parameters:

• employee
• companyEmployeeId

The API resources that support the employee filter include:

• /assets/devices
• /assets/services
• /orders (HTTP GET method)
• /employees

Using URI Parameters to Obtain a Single Item

Many of the resources in this API return a collection of items (e.g., /assets/devices). However, where it makes sense, there are also many related resources that return a single item instead of the entire collection (/assets/devices/{id}). Often these calls for a single item include more detail data than what is provided within the collection response.

These calls for a single item are commonly performed by appending a URI parameter to a collection endpoint, with that parameter being set to the ID of the specific item desired.

URI Parameters

A Uniform Resource Identifier (URI) is a string of characters used to identify a specific resource. The most common form of URI is the Uniform Resource Locator (URL).

The URI parameter is a parameter that is incorporated into the URL itself, rather than appended on the end of the URL (as commonly seen with query strings). For this API, the URI parameter is always set to the ID of the specific resource item that you wish to access.

In the API documentation, you will see these URI parameters referenced as “{id}” within the resource signature (e.g., /catalog/devices/{id}).

/catalog/devices/9194831760

Errors

This API returns a standard HTTP status code with every response to indicate whether your request had succeeded or failed.

Status codes within the 200 range typically indicate that the request was processed successfully. Codes within the 400 range indicate an error resulting from the request data provided by the caller (e.g., a required parameter was missing from the request). And codes within the 500 range indicate an error triggered by an issue on Tangoe’s servers.

Video Tutorial

The following video explains how this API returns error responses to help you pinpoint your issue and get you back on track quickly.

We also recommend browsing all of our tutorials in our Video Library at http://mobproc.tv.

Supported HTTP Status Codes

The following status codes are currently supported:

Error Messages

If an error does occur, the following error message information will be included within the response body:

• status – One of the supported HTTP status codes listed above (e.g., 400).
• id – Unique string identifying the specific occurrence of the error.
• errorCode – Tangoe-assigned code indicating the type of error that occurred.
• message – Description of the what caused the error and/or how to resolve it.

Here is an example of an error message for a missing (required) parameter:

{
  "errorCode": "400-Region_id-Account-Id-error",
  "id": "tghwn",
  "message": "Region ID or Service ID must be passed in.",
  "status": 400
}