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 page 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:

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