API referenceEndpoints
Authentication
OAuth 2.0 client credentials.
Get an access token
/v1/oauth/tokenOAuth 2.0 client credentials. Send your client id and secret with HTTP Basic auth (preferred), or as client_id and client_secret in the body, never both.
The body can be JSON or application/x-www-form-urlencoded. The token works for one hour (expires_in); reuse it until then.
Ask for fewer scopes than the key has with scope (space-separated); without it the token gets all of them.
Limits: 10 tokens a minute per key, 30 requests a minute per IP address. After 10 failed attempts from one address in 10 minutes, it gets 429 too_many_failed_attempts for 10 minutes.
Keys of accounts that aren't active (not set up, suspended or canceled) and of partners that aren't active get 403 account_inactive. A key with an IP allowlist gets 403 ip_not_allowed from any other address.
Request body
grant_typestringRequiredAlways
client_credentials.One of:
client_credentialsscopestringSpace-separated scopes, a subset of the key's. Default: all of them.
Up to 1000 characters
client_idstringThe key's client id (
ac_cli_…), if not sent with HTTP Basic.Up to 200 characters
client_secretstringThe key's secret (
ac_sk_…), if not sent with HTTP Basic.Up to 200 characters
Responses
200A bearer token.
access_tokenstringRequiredThe bearer token (
ac_at_…). Send it asAuthorization: Bearer <token>.token_typestringRequiredAlways
Bearer.expires_inintegerRequiredSeconds until it expires (3600).
scopestringRequiredThe token's scopes, space-separated.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
Example request
curl https://api.assistcall.ai/v1/oauth/token \
-u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
-d grant_type=client_credentials \
--data-urlencode 'scope=calls:read contacts:read'Example response (200)
{
"access_token": "ac_at_Zk2Rq8sV0pLm3XbN7cTy4uWe9hJd1fGa6KoQi5Ar",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "account:read calls:read contacts:read"
}Revoke an access token
/v1/oauth/revokeEnds a token before it expires (RFC 7009). Authenticate with the key's client credentials (Basic or body) or with a bearer token of the same key. The answer is the same whether or not the token existed. To stop a key altogether, revoke the key on the Developers page of your portal: its tokens stop working at once.
Request body
tokenstringRequiredThe access token to revoke.
Up to 200 characters
token_type_hintstringIgnored; accepted for RFC 7009 clients.
Up to 40 characters
client_idstringThe key's client id, if not using HTTP Basic or a bearer token.
Up to 200 characters
client_secretstringThe key's secret, if not using HTTP Basic or a bearer token.
Up to 200 characters
Responses
200Revoked (or there was nothing to revoke).
okbooleanRequiredAlways true.
- 400
invalid_requestA parameter or body field is missing or invalid; the message names it. - 401
authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials). - 403
permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write. - 429
rate_limitToo many requests: wait Retry-After seconds. - 500
serverSomething went wrong on our side. Retry with backoff.
Errors share one shape. See Errors.
- 400
Example request
curl https://api.assistcall.ai/v1/oauth/revoke \
-u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
-d token=ac_at_Zk2Rq8sV0pLm3XbN7cTy4uWe9hJd1fGa6KoQi5ArExample response (200)
{
"ok": true
}