# Alva Agent Authentication

Alva uses user-scoped authentication for private account data, API keys, billing, brokerage connections, live execution, and playbook writes.

## Supported auth surfaces

- Browser users sign in through the Alva web app.
- API and OpenAPI examples use bearer authentication with a user-scoped JWT or API key.
- MCP access may require authorization before tool calls can read private resources or mutate playbooks.
- Public discovery resources such as `/llms.txt`, `/llms-full.txt`, `/openapi.json`, `/pricing.md`, `/auth.md`, `/onboarding.md`, `/sandbox.md`, and `/status` do not require authentication.

## API key flow

1. Sign in to Alva.
2. Open `/apikey`.
3. Create an Alva API key.
4. Copy the plain key immediately; Alva does not replay it after the save dialog closes.
5. Send authenticated API requests with `Authorization: Bearer <user_token_or_api_key>`.

## Bearer token rules for agents

- Never expose tokens in prompt-visible logs, screenshots, or shared playbooks.
- Ask for explicit user confirmation before billing, brokerage, live execution, or playbook write actions.
- Treat `401` as missing or expired credentials and ask the user to sign in again.
- Treat `403` as insufficient permissions and explain which user action or scope is required.
- Treat `429` as rate-limited and back off using `Retry-After` or `RateLimit-Reset` when present.

## Agent auth endpoints

Alva does not currently advertise a public OAuth dynamic client registration endpoint, claim endpoint, or revocation endpoint for unauthenticated agents. Agents should use the user-facing sign-in and API key flow until OAuth/OIDC metadata is published.

## References

- [OpenAPI spec](https://alva.ai/openapi.json)
- [API docs](https://alva.ai/api-docs)
- [API docs markdown](https://alva.ai/api-docs.md)
- [MCP integration notes](https://alva.ai/mcp.md)
- [Webhook status](https://alva.ai/webhooks.md)
- [Developer guide](https://alva.ai/developers)
- [Machine-readable pricing](https://alva.ai/pricing.md)
- [Agent sandbox](https://alva.ai/sandbox.md)
- [Agent status page](https://alva.ai/status)
- [Agent discovery](https://alva.ai/agent.json)