# Aetherya authentication

How an agent authenticates to Aetherya today, and what is coming.

## Today: API key (works now)

1. A human creates the account at https://app.aetherya.ai/signup (Google, or email plus an emailed code; the form has bot protection the human completes).
2. The human creates a key at https://app.aetherya.ai/dashboard/settings?tab=api-keys and gives it to the agent.
3. The agent sends `Authorization: Bearer aeth_live_...` to `https://api.aetherya.ai`.

A key acts as the user who created it, on that user's default workspace. `x-aetherya-workspace-id` is optional; send it only to target a different workspace the user belongs to (list them with `GET /api/workspaces`). Keys cannot manage keys, members, billing, or organization settings. The human revokes a key from the same settings tab.

Limits: 60 requests per minute per key. Over the limit you get `429` with `{"code":"RATE_LIMIT_EXCEEDED","retryAfterSeconds":N}`; wait that long. A `429` with `INSUFFICIENT_SESSIONS` means the plan allowance is used up, not a rate limit.

## Coming: delegated agent auth (not enabled yet)

Aetherya is adding discovery-first delegated auth so an agent can register itself, run a small trial, and have its human approve a workspace binding with one click. It is not enabled in production. You can tell it is live when `GET https://api.aetherya.ai/.well-known/oauth-protected-resource` returns 200. Until then the endpoints below return 404 or 503, and `npx @aetherya/mcp auth` is not available; use an API key.

When enabled:

- Discovery: `/.well-known/oauth-protected-resource`, `/.well-known/oauth-authorization-server`, `/.well-known/jwks.json` on `https://api.aetherya.ai`
- Registration: `POST /agent/identity` (`service_auth` with the user's email, or `anonymous`)
- The human approves at `https://app.aetherya.ai/claim`, reviewing the workspace and the exact capabilities
- Tokens: `POST /oauth2/token` (short-lived, workspace-bound); revoke with `POST /oauth2/revoke`