Skip to main content

Authentication

Authenticate every API request using an API key created in the dashboard.

You can create and manage keys here: /client/api-keys

For full key lifecycle details (create, copy once, revoke), see the User Guide page:

Base URL​

https://api.yourcalls.ai

Supported authentication methods​

Your API key goes in a request header. Both of these are accepted, and you only need one.

Authorization: Bearer YOUR_API_KEY

2) x-api-key header​

x-api-key: YOUR_API_KEY

Passing the key in the URL is not supported​

An earlier version of this API accepted the key as an ?api_key= query parameter. It no longer does, and a request that only supplies the key that way is rejected with 401 Missing API key.

Anything in a URL is written down in places you do not control: server access logs, proxy and load balancer logs, browser history, and the Referer header sent to any third party. A key that reaches those places has to be treated as compromised. Headers are not logged this way, so send the key in a header instead.

Example request​

curl --request POST "https://api.yourcalls.ai/public/v1/calls" \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "assistant_id": "12345678-1234-4234-9234-1234567890ab",
    "target_phone_number": "+442079460958"
  }'

How auth is applied​

  • API keys are company-scoped.
  • Requests automatically run under the key's company context.
  • Expired or revoked keys are rejected.

Common auth errors​

  • 401 Missing API key
  • 401 Invalid API key
  • 401 API key revoked
  • 401 API key expired

Security best practices​

  • Store keys in secret managers, never in client-side code.
  • Rotate keys regularly.
  • Revoke compromised keys immediately.
  • Use separate keys per integration (for easier isolation and revocation).