Authentication

All requests to the REST and RealTime API require you to authenticate yourself in order to use them. We support two kinds of authentication for customers: Bearer Tokens and Basic Authentication. There’s also a third kind called Integrator Authentication for enterprise-level customers, vendors or partners who have a large amount of shared customers with us, but that most likely does not apply to you.

Each has its own advantages and drawbacks, which will explain next. The great news is that you can mix and match these up as you see fit.

If you are not sure what kind of authentication to use with our API, chances are that it’s easier to start with HTTP Basic Authentication. This type is widely available by most, if not all, modern HTTP clients. Furthermore, you won’t have to worry about token expiration and renewal. You’ll be able to use all REST API endpoints, which will likely cover most use cases.

This authentication method requires you to first make a request to our /auth/login endpoint using your username and password. In return, you receive a token that represents your authentication session which you use in place of your username and password in future REST calls and for the RealTime API.

Advantages:

• If you have multiple accounts with us, this method allows you to perform operations on all of your accounts using the same bearer token by performing an account masquerade operation.
• The RealTime API only supports tokens, so if you wish to use it, you must use this method.

Drawbacks:

• You must keep track of the token expiration date and periodically refresh it. This adds slightly more complexity to your business logic.

This authentication method is widely supported by many HTTP client libraries. In order to this use, you must include your username and password in an Authorization header on each request to the REST API in a specially formatted, base-64 encoded string.

Advantages:

• The business logic of making REST API calls is much simpler since you don’t have to first login and maintain a valid token.
• Integration with our voice, text and rapidresponse endpoints are faster since they can be performed with a single HTTP request.

Drawbacks:

• If you have multiple accounts with us, this authentication method cannot guarantee that you authenticate against the correct account using the username and password since that user might have access to multiple accounts.
• The RealTime API does not support this authentication method.