Authentication

To interact with the Ubity API, you will need an API key. You can request an API key by writing to Ubity Support.

The Ubity API expects an API key to be included in all API requests to the server as part of the GET or POST parameters, using the key parameter:

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/extensions?key=KKKK"

What a key carries

An API key is not only a secret: it also defines what the requests made with it are allowed to do.

• A key always belongs to an application, which conveys a set of permissions. Some endpoints require a specific permission to be granted to the application.
• A key may be bound to a user; in that case a permission must be granted both to the application and to the user.
• A key may be bound to an account, in which case all the requests made with it are limited to the realm of that account. When a key is not bound to a single account (for example an integrator's key which manages several customer accounts), the endpoints that operate on an account accept an account parameter to select the account to work on.

A key may also carry a few restrictions: a list of allowed source IP addresses, an absolute expiration date, or an inactivity timeout. Requests that do not satisfy these restrictions are answered with a 401 error and a diagnostic explaining the reason.

Keeping the key secret

The API key is a secret; treat it like a password. Do not embed it in client-side code delivered to end users, and take reasonable measures to keep it out of logs and version control.