Authentication
Every request needs an API key. Keys look like sk_live_ followed by 40 characters.
Sending the key
Section titled “Sending the key”Send the key as a bearer token in the Authorization header:
curl "$BASE_URL/agents" \ -H "Authorization: Bearer $SAHAY_API_KEY"The X-API-Key header works too:
curl "$BASE_URL/agents" \ -H "X-API-Key: $SAHAY_API_KEY"If a request carries both headers, the Authorization header is used.
Creating and revoking keys
Section titled “Creating and revoking keys”Organization admins create and revoke keys in the Sahay dashboard under Developers.
- The full key is shown once, when you create it. Sahay stores only a hash, so it cannot be shown again. If you lose a key, revoke it and create a new one.
- A key you revoke stops working on its next request.
- An organization can hold at most 10 active keys.
- Keep keys on your server. Do not put them in a web page, a mobile app or a public repository.
Authentication errors
Section titled “Authentication errors”| Status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key |
No Authorization or X-API-Key header. |
| 401 | invalid_api_key |
The key is malformed, unknown or revoked. |
| 403 | developer_api_disabled |
The Developer API is not enabled for your organization. Email sales@sahay.io. |
| 503 | service_unavailable |
The key could not be checked right now. Retry shortly. |
Beyond the key check, voice endpoints also require that your plan includes AI voice calling. See Errors for the full table.
What a key can do
Section titled “What a key can do”A key acts for its whole organization. Every endpoint in these docs is available to every key, and every request is scoped to the organization the key belongs to. There are no per-key permissions.