Skip to content

API referenceEndpoints

Authentication

OAuth 2.0 client credentials.

Get an access token

POST/v1/oauth/token

OAuth 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_typestringRequired

    Always client_credentials.

    One of: client_credentials

  • scopestring

    Space-separated scopes, a subset of the key's. Default: all of them.

    Up to 1000 characters

  • client_idstring

    The key's client id (ac_cli_…), if not sent with HTTP Basic.

    Up to 200 characters

  • client_secretstring

    The key's secret (ac_sk_…), if not sent with HTTP Basic.

    Up to 200 characters

Responses

  • 200A bearer token.
    • access_tokenstringRequired

      The bearer token (ac_at_…). Send it as Authorization: Bearer <token>.

    • token_typestringRequired

      Always Bearer.

    • expires_inintegerRequired

      Seconds until it expires (3600).

    • scopestringRequired

      The token's scopes, space-separated.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

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

POST/v1/oauth/revoke

Ends 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

  • tokenstringRequired

    The access token to revoke.

    Up to 200 characters

  • token_type_hintstring

    Ignored; accepted for RFC 7009 clients.

    Up to 40 characters

  • client_idstring

    The key's client id, if not using HTTP Basic or a bearer token.

    Up to 200 characters

  • client_secretstring

    The key's secret, if not using HTTP Basic or a bearer token.

    Up to 200 characters

Responses

  • 200Revoked (or there was nothing to revoke).
    • okbooleanRequired

      Always true.

    • 400invalid_requestA parameter or body field is missing or invalid; the message names it.
    • 401authenticationNo access token, or it’s invalid or expired (or, at the token endpoint, wrong client credentials).
    • 403permissionThe token lacks the scope, the IP isn’t allowed, the account isn’t active, or a sandbox key tried to write.
    • 429rate_limitToo many requests: wait Retry-After seconds.
    • 500serverSomething went wrong on our side. Retry with backoff.

    Errors share one shape. See Errors.

Example request

curl https://api.assistcall.ai/v1/oauth/revoke \
  -u "$ASSISTCALL_CLIENT_ID:$ASSISTCALL_CLIENT_SECRET" \
  -d token=ac_at_Zk2Rq8sV0pLm3XbN7cTy4uWe9hJd1fGa6KoQi5Ar

Example response (200)

{
  "ok": true
}

Try "token", "webhook signature", "rate limit" or "custom domain".