Authentication

Every request carries an API key in the Authorization header.

Authorization: Bearer sapi_...

Keys start with sapi_. Create them in the portal at platform.simular.ai. A key is shown once at creation; store it in a secret manager or an environment variable, never in source.

Check a key

curl -s "$SAI_API_URL/v1/agents/auth" \
  -H "Authorization: Bearer $SAI_API_KEY"

{ "ok": true, "userId": "3fA9kQ2xYz", "authType": "apiKey" }

A missing or revoked key returns 401.

Firebase ID tokens

The same endpoints also accept a Firebase ID token from a signed-in Sai session in the Authorization header. That is how the portal and the sai CLI call the API. Key management under /v1/account/keys accepts only a Firebase session; an API key cannot create, list or revoke keys. See Keys.

Organisation Keys and Tenant tokens

An Organisation has keys of its own. They also start with sapi_, but they manage Tenants and cannot run tasks. To run tasks for a Tenant, exchange the Organisation Key for a Tenant token and send that in Authorization instead.

Who can use a key

• Paid accounts: any live key on the account.
• Free accounts: one key, after phone verification. Before verification, key creation returns 403 with { "error": "phone_verification_required" }. The check reads the sign-in token, so verify the phone first and then sign in; if you verified it just now, sign in again before creating the key.

Note

Free-account keys are available from October 1. Today's staging accepts API keys from paid accounts only.

Errors

Error bodies are JSON with one error string:

{ "error": "Message rate limit exceeded. Maximum 600 messages per hour." }