Application and devices need to authenticate themselves to the service to allow access to perform any API operation. Every web service call is stateless and does not carry authentication information in a session. This means, regardless of the factors (or a combination of factors) chosen for authenticating to the server, client application must include the credentials in every call. The authentication specification is designed around the following client types:

Unattended devices

Devices that do not interact with human user or software components that drive such devices are considered confidential clients. Credentials stored in such applications are expected to be static and secured by means and capabilities of the operating system. Such applications can use following methods to present their credentials to service.

  • An API Key, Secret This method is also expected to carry device context and service provider endpoint is expected to associate API keys to a real user and role.
  • Login, password Used by devices or applications that will at least have one interaction to the user during an activation step. The device or software component is expected to “activate” itself and store only the API keys for subsequent operations.

Applications requiring user interaction

A native application is a client installed and executed on the devices used by interactive users. Protocol data and credentials are easily accessible (and often visible) to the user. It is assumed that any client authentication credentials included in the application can be provided on request any time.

Following methods can be used by client applications to authenticate:

  • Login, password Client apps must use some kind of dialog to enter user / password information and can cache the credentials for a reasonable period.
  • Federated authentication Used for single-sign-on (SSO) infrastructure such as SAML. Implementations of such authentication methods vary and are typically provided by custom plugins.

Authentication information is included as HTTP headers. All REST API calls are expected to use SSL authentication. tagVUE™ services do not support non-SSL based API invocations.

API Key based authentication

If API key based authentication is chosen as primary method of authenticating a device or application, every call includes an “Authorization” HTTP header formed as following: 

Authorization: [APIKEY]:[SECRET]

Where [APIKEY] and [SECRET] are pre-provisioned on the server. A failed authentication will return the HTTP status code 401. Here is an example: 

Authorization:0B79E2B2-00BF-44B0-9F95-CB5ADE5599EE:CB5ADE5599EE

API keys are normally associated with a real user or role. Depending on authorization associated with the role and server application policies, certain API calls might be rejected with failed authentication even though the actual API keys are correct.

User, password based authentication

For user/password based authentication method, service calls includes the “Authorization” header in Basic HTTP authentication mode (RFC 2617). In this case, username password text is concatenated with ‘:’ as separator character. The resulting string is then base-64 encoded and included in the “Authorization” header prefixed with string “Basic”.

Here is an example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

A failed authentication will return the HTTP status code 401.

Federated authentication

Implementations vary, and are provided by custom plugins. A typical authentication flow involves a third party identity provider agent that would intercept the service endpoints and expect an authenticated request comprising of tokens generated by identity provider service.

AUTHORIZATION tagVUE server applications use a module specific fine grained privileges that are grouped into roles and application users permissions are determined by such roles. Depending on the authentication, the associated user’s role is used to determine the operations available to the API. Service endpoints other than tagVUE™ server applications implement their own mechanism for managing privileges that define what web service calls and endpoints are available to which users and what isn’t. Failed authentication situations should always return a “401” status code and failed authorization should return a “403” status code.