For: Admins
Authenticate API requests with a key
Send your key as a bearer token to the Admin Panel's API for a manage key or the portal's API for a hub key, and limit it to your IP addresses.
In this article4 sections
This page covers where to send each kind of API keyKey A secret token, created under Integration, that lets your own software use the hub's API., how to send it, and why a key is refused.
Addresses
| Key | Base address | Example |
|---|---|---|
| Manage key | https://prd-api-manage.caseactive.com/v1/<hub id>/ | https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases |
| Manage key, imports | https://prd-api-manage.caseactive.com/v1/integration/<hub id>/ | https://prd-api-manage.caseactive.com/v1/integration/ca-7e6d5c4b3a2f10/imports |
| Hub key | https://prd-api-app.caseactive.com/v1/<hub id>/ | https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cases |
| Hub key, one case | https://prd-api-app.caseactive.com/v1/<hub id>/<case id>/ | https://prd-api-app.caseactive.com/v1/ca-7e6d5c4b3a2f10/cc-1a2b3c4d5e6f70/posts |
Your hub ID is ca- and 14 characters. It shows as Hub Id on the Info page of any case in your portal, with a copy button. A case ID is cc- and 14 characters, shown there as Case Id.
Sending the key
Send the key in the Authorization header of every call, after Bearer and a space:
curl https://prd-api-manage.caseactive.com/v1/ca-7e6d5c4b3a2f10/roles \
-H "Authorization: Bearer YOUR_API_KEY"
- Send JSON bodies with
Content-Type: application/json. - A key doesn't expire. It works until an Admin switches it off or deletes it in Integration › Keys.
- Every call signs in afresh: there's no session or token to exchange.
- Dates and times come back in UTC.
Limiting where it's used
Under Source CIDR, a key can be limited to your system's public IPv4 address, such as 203.0.113.10, or a range, such as 203.0.113.0/24. The API takes IPv4 connections only, so an IPv6 address or range is refused when you save it. A call from anywhere else is refused with 401 LoginSourceIpException. To change the range, see Restrict or revoke an API key.
When a key is refused
Every refusal comes back as an error body whose message names it; see Handle API errors and status codes.
| Status | message | Why | What to do |
|---|---|---|---|
| 401 | Unauthorized | No key was sent, or what was sent isn't a key | Check the Authorization header |
| 401 | HostNotFoundException | The hub ID in the address doesn't exist | Copy Hub Id again |
| 401 | HostPurgingException | The hub is being deleted | Ask an Admin of your hub |
| 401 | SessionNotFoundException | The key was deleted, or belongs to another hub | Use a current key for this hub |
| 401 | LoginKeyInactiveException | The key is switched off | Ask an Admin to switch it on |
| 401 | LoginKeyWrongApiException | A manage key was sent to the hub key's address, or the other way round | Use the address for the key's type |
| 401 | LoginSourceIpException | The call came from outside the key's range | Call from an allowed address, or widen the range |
| 401 | LoginSourceCidrException | The key's saved range can't be read | Correct Source CIDR |
| 403 | BotNotAllowedException | A manage key called something it can't use | See Understand what the API can do |
| 403 | ManageBillingInactiveException | Your hub's Admin Panel is locked after a failed payment (manage key only) | Ask an Admin to update the payment method |
| 403 | BillingReadOnlyException | Your hub's subscription has lapsed and its portal is read-only, so a hub key can read but not change anything | Ask an Admin to restart the subscription |
| 403 | CaseClosedException | A hub key tried to change a closed case | Reopen the case first |
| 404 | CaseNotFoundException | A hub key named a case that doesn't exist, or isn't in your hub | Check the case ID |
| 503 | LoginSessionException | The hub was too busy to check the key | Try again shortly |
A 401 always means the key itself was refused, so a sync can stop and alert someone. Other errors are about the call.