Authentication

Every Vaaya surface takes the same API key as a bearer token. Keys never expire on their own. Create, name, and revoke them at /api-keys.

The header

Authorization: Bearer vaaya_sk_...

Send this header on every request. The LLM router accepts the same key as an OpenAI-style api_key. MCP accepts it as a bearer header for headless clients.

Getting a key

Every account gets a key at signup. Sign up or log in and copy it from the keys page. You can create more keys, name them per environment, and revoke any of them at any time. Add a card or buy a prepaid pack to add credit.

Spend ceilings

Each key can carry a spend ceiling for a window you pick — per day, per week or per month. Once the key has spent it, its calls return 402 api_key_limit_exceeded with the ceiling, the period and what it has spent; the rest of your account is untouched. Set it when you create the key or from the key’s row on /api-keys, where you can also pause a key (it keeps authenticating, but every paid call is refused) or rotate its secret in place.

The ceiling holds on every surface a key can spend through: POST /api/run/*, paid fetch, and the LLM router — where a streaming completion is refused before the first byte rather than part-way through.

Managing agents over the API

GET /api/v1/agents returns one row per key — label, external id, ceiling, period, spend this period, and last use — so a program can read the same picture /agents shows. POST /api/v1/agents mints one (label, ceiling_cents, ceiling_period, external_id) and returns the secret once; PATCH /api/v1/agents/{id} changes the label, ceiling, period or paused; POST /api/v1/agents/{id}/rotate swaps the secret in place; DELETE /api/v1/agents/{id} revokes it.

A key cannot mint keys. The write calls need either a signed-in session or your account’s primary key — the first one on /agents — so a leaked agent key stays boxed inside its own ceiling. Anything else gets 403 key_cannot_mint_keys.

Key hygiene

Your key can spend your credit balance. Keep it in a secret store, not in client-side code.
Use one named key per deployment, or one per agent, so you can revoke or cap one without touching the rest.
A 401 invalid_token means the key is missing or revoked. Nothing is charged.