API Authentication / Authorization

Requests to IDI’s APIs are authenticated to ensure the resources provided by the API are only accessed by authorized clients. Depending on the API being used different levels of authorization may be required. Details on the required level of authorization will be indicated on the API operation documentation if more than an authenticated user is required.

Authentication

Authentication of IDI’s APIs is accomplished using a WS-Trust protocol. Specifically, IDI relies on a security token supplied by a Security Token Service (STS) to authenticate API requests. The request will require a Simple Web Token (SWT) for authentication. The following diagram illustrates IDI’s implementation of the WS-Trust protocol.

Simple Web Token (SWT)

A Simple Web Token (SWT) is the primary form of authorization for IDI’s APIs. To get a new SWT a client must request one from the Security service using the api/login method. The URI for this API is https://api.idibilling.com/securitytoken/1xa/environment/api/login. Once an SWT has been obtained it should be passed along to all future API requests in the form of an Authorization header. The header key should use the following format WRAP access_token=”<security token>”.

Authorization

Authorization is handled server side by the webservice by checking the security token for the appropriate claims, and expiration information. All the required information to do the authorization is included with the security token and is signed by IDI to prevent tampering. Any attempt to alter a security token will invalidate the token and will cause the authorization of that token to fail.

To limit potential security threats a security token has a predefined expiration date. A new security token should be acquired before this expiration date to prevent authorization failures. It is IDI’s recommendation that clients refresh their security tokens after it has reached 80% of its lifetime to prevent these scenarios.

Web Service Users

Web service users are most basic type of user. IDI will set one of these users up for clients to use for API access in any of their environments. Web service users when accessing an API will not be restricted to accessing any information within the environment, for this reason the credentials for the web service user should always be kept secure and never transmitted to client facing application. To obtain the credentials for your web service user please see your Account Manager for details. You should consider using a web service user if

• Recording the actual user for auditing / logging is not a concern
• Backend or automated processes

Application Users

Application users are users which are setup by clients for access to the system. Application users by themselves cannot directly communicate with IDI APIs, instead an application user must login using both their own credentials supplied through a login screen, and an underlying web service user’s credentials supplied by backend configuration. An application user differs from a web service user in that an application user will have a set of claims associated to them that differ from environment to environment. These claims will help dictate what API operations the user should or should not have access to. You should consider using an application user if

• The user making the updates needs to be recorded for auditing purposes.
• The client application wishes to check the claims of a user.
• Server side restrictions such as customer limit tos need to be enforced on the authenticated user.