DevelopersGet started
Authentication
The API uses the OAuth 2.0 client credentials flow. An API key is a client ID and a secret that stay on your server. You exchange them for an access token that lasts one hour, and send that token with every request.
On this page
How it works
1POST /v1/oauth/token
grant_type=client_credentials, with client ID + secret
2200: an access token
{ "access_token": "ac_at_…", "expires_in": 3600 }
3GET /v1/calls
Authorization: Bearer ac_at_…
4200: your calls
{ "data": [ … ], "has_more": false }
- Reuse the same token for every request for up to an hour
5Any request after the hour
Authorization: Bearer ac_at_… (expired)
6401 invalid_token
so get a new token (step 1) and send the request again
There are no refresh tokens: when a token expires, ask for a new one the same way. Asking a minute or two early avoids a failed request at the boundary.
API keys
- Client ID
ac_cli_and 20 letters and digits. Not secret: it names the key, and you'll see it in your dashboard's key list.- Client secret
ac_sk_and 40 letters and digits. Shown once, when the key is created. AssistCall keeps only a keyed hash of it (HMAC-SHA256) and its last four characters, so nobody can show it to you again; if you lose it, create a new key.- Scopes
- What the key may do, chosen when you create it. Keys can't be edited: to change scopes, create a new key and revoke the old one. See Scopes.
- Allowed IP addresses
- Optional. Up to 20 addresses or ranges (like
203.0.113.0/24, IPv6 too). See IP allowlists.
Account owners create and revoke keys on the Developers page of the dashboard; partners on the API page of the partner portal. Teammates can see the key list but can't create or revoke keys. An account or partner can have up to 10 active keys.
A reseller's clients don't get keys: their accounts have no Developers page, and the reseller works on their data with its own partner key (Partner API).
Getting a token
POST /v1/oauth/token with grant_type=client_credentials. Send the client ID and secret one of three ways, but only one per request:
- HTTP Basic (recommended):
Authorization: Basic base64(client_id:client_secret), with a form body. - JSON body:
client_idandclient_secretnext togrant_type, withContent-Type: application/json. - Form body: the same fields as
application/x-www-form-urlencoded.
Add scope (space-separated) to get a token with fewer permissions than the key has, for example a reporting job that only needs calls:read. Leave it out to get all of the key's scopes.
# 1. HTTP Basic (recommended): client id and secret in the Authorization header
curl https://api.assistcall.ai/v1/oauth/token \
-u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
-d grant_type=client_credentials
# 2. JSON body
curl https://api.assistcall.ai/v1/oauth/token \
-H "Content-Type: application/json" \
-d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$ASSISTCALL_CLIENT_ID\",\"client_secret\":\"$ASSISTCALL_CLIENT_SECRET\"}"
# 3. Form body, with a narrower scope than the key has
curl https://api.assistcall.ai/v1/oauth/token \
-d grant_type=client_credentials \
-d client_id="$ASSISTCALL_CLIENT_ID" \
-d client_secret="$ASSISTCALL_CLIENT_SECRET" \
--data-urlencode "scope=calls:read messages:read"{
"access_token": "ac_at_4kQ9w2ZtV7nB1xR8mP3sL6dF0hJ5yC2gT9aE7uW1",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "calls:read messages:read"
}| Status and code | Means |
|---|---|
400 invalid_request | A missing grant_type, an unexpected parameter, or credentials sent twice (header and body). |
400 unsupported_grant_type | Only client_credentials is supported. |
400 invalid_scope | You asked for a scope the key doesn’t have. |
401 invalid_client | The client ID or secret is wrong, or the key was revoked. |
403 ip_not_allowed | The key has an IP allowlist and this address isn’t on it. |
403 account_inactive | The account isn’t set up yet, or is suspended or canceled (or the partner account isn’t active). |
429 token_rate_limited | More than 10 tokens for this key in a minute. Reuse tokens. |
429 rate_limited | More than 30 token requests from this IP address in a minute. |
429 too_many_failed_attempts | 10 failed sign-ins from this address in 10 minutes. It’s blocked for 10 minutes. |
Using a token
Send the token in the Authorization header of every request:
GET /v1/calls HTTP/1.1
Host: api.assistcall.ai
Authorization: Bearer ac_at_4kQ9w2ZtV7nB1xR8mP3sL6dF0hJ5yC2gT9aE7uW1Without it you get 401 missing_token; with an expired, revoked or malformed token, 401 invalid_token. A token can only do what its scopes allow: anything else is 403 insufficient_scope. Tokens never go in URLs or query strings.
Refreshing tokens
Keep the token in memory with its expiry time, get a new one a minute before it runs out, and retry once on a 401. These drop-in helpers do exactly that:
# In a shell script, get a token once and reuse it for the run (it lasts an hour)
ASSISTCALL_TOKEN=$(curl -s https://api.assistcall.ai/v1/oauth/token \
-u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
-d grant_type=client_credentials | jq -r .access_token)
curl https://api.assistcall.ai/v1/calls -H "Authorization: Bearer $ASSISTCALL_TOKEN"Revoking tokens and keys
A single token: POST /v1/oauth/revoke with token in the body. Authenticate with the key's client ID and secret (HTTP Basic or in the body), or with the token itself as a bearer token. The answer is always { "ok": true }, whether or not the token still existed, as the OAuth revocation standard (RFC 7009) asks.
curl https://api.assistcall.ai/v1/oauth/revoke \
-u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
-d token="$ASSISTCALL_TOKEN"A whole key: choose Revoke next to it on the Developers page (or the partner portal's API page). The key and every token it was given stop working right away; this can't be undone.
Storing secrets safely
- Server side only. The secret, and the tokens, belong on your server. Never put them in a web page, a mobile app or anything you ship to customers; anyone can read those. (Browsers can't call the API from your own site anyway: it only allows this docs site's Try it console, which sends a key you enter only to the API and keeps it in that tab's memory.)
- Environment variables or a secret manager, not source code. Keep
.envfiles out of git. - Don't log them. Redact the
Authorizationheader in request logs and error reports. - One key per app or script, with only the scopes it needs, so a leak is contained and easy to revoke.
- Leaked a secret? Revoke the key now, then create a new one. Revoking ends its tokens at once, so nothing else is needed.
IP allowlists
When you create a key you can list the addresses allowed to use it, one per line: single addresses (203.0.113.10) or ranges (198.51.100.0/24), IPv4 or IPv6, up to 20. Requests from anywhere else, for a token or with one, are refused with 403 ip_not_allowed. Leave the list empty to allow any address.
Use it when your servers have fixed outgoing addresses. If your provider's addresses change (many serverless platforms), leave it empty and rely on keeping the secret safe.
Rotating keys
Because each account can have several keys, you can rotate without downtime:
- Create a new key with the same scopes (and allowlist).
- Deploy it to your app's secret store and restart or reload.
- On the Developers page, check that the old key's Last used time stops moving and the new key's starts.
- Revoke the old key.
Rotate on a schedule that suits you (every 90 days is common), whenever someone with access to the secret leaves, and immediately if it may have leaked.