Authentication

The SIP Caller REST API authenticates requests with API keys. Each API key has a secret token, which your application sends in the Authorization header of every request.

Create an API key

API keys are created from the Web Console, in Settings > API Keys, by a user with the Administrator role. When creating the key, you choose:

• A name, to identify the application that uses it.
• An expiration date. After that date, the key stops working. The expiration can't be extended later.
• The roles granted to the key, which define what the application can do. The roles can't be changed later.

When the key is created, SIP Caller shows its token only once. Copy it and store it in a safe place, such as a secrets manager. SIP Caller doesn't store the token, so it can't be recovered: if you lose it, create a new API key.

See API Keys for a step-by-step guide.

Authenticate requests

Send the token as a Bearer token in the Authorization header:

Authorization: Bearer API_KEY_TOKEN

Every request must be authenticated. Keep in mind that:

• An API key belongs to a single account, so the ACCOUNT_ID in the URL must be the account where the key was created.
• Requests must be made over HTTPS.
• The token is a secret, and grants access to your account. Don't include it in client-side code, such as web pages or mobile apps, and don't commit it to source code repositories.

Roles

Each endpoint requires the API key to have at least one of the following roles:

Role	Allows
Campaign Admin	Full access to campaigns, campaign numbers, black lists, contact lists and campaign reports.
Campaign Reader	Read-only access to campaigns, campaign numbers, black lists, contact lists and campaign reports.
Campaign Number Admin	Read, add and delete the numbers of campaigns. Can be restricted to specific campaigns.
Campaign Number Provider	Add numbers to campaigns, without being able to read or delete them. Can be restricted to specific campaigns.

Grant each application only the roles it needs. For example, a web form that pushes new leads to a campaign only needs the Campaign Number Provider role, restricted to that campaign.

Authentication errors

Status	When
401 Unauthorized	The Authorization header is missing, or the token is malformed, invalid or expired.
403 Forbidden	The token is valid, but the API key was deleted, belongs to another account, or doesn't have a role that allows the operation.

See Errors for the format of error responses.

Revoke an API key

To revoke the access of an application, delete its API key from Settings > API Keys. Requests made with the token of a deleted key fail immediately with 403 Forbidden.

We recommend rotating keys periodically: create a new key, update your application to use it, and then delete the old one.