> ## Documentation Index
> Fetch the complete documentation index at: https://docs.attaxr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Sessions, API keys, roles, and the access gates Aquila applies.

Every Aquila API request carries a credential. Requests without a valid
credential receive `401`. There are three credential types, and one session
for all of them.

## Credential types

### API key

Aquila creates one API key for each user at sign-up. The key starts with
`aquila_`. Copy it from Settings in the dashboard.

Send the key in either header:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
# Header form
curl https://aquila.attaxr.com/api/scans -H "x-api-key: aquila_YOUR_KEY"

# Bearer form
curl https://aquila.attaxr.com/api/scans \
  -H "Authorization: Bearer aquila_YOUR_KEY"
```

API keys give the same access as your session. Keep them secret. If a key
leaks, rotate it from Settings.

### Session cookie

The dashboard uses a browser session. Sign in through Better Auth:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
curl -X POST https://aquila.attaxr.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'
```

Better Auth sets the `better-auth.session_token` cookie. Send that cookie on
later calls. The auth endpoints for sign-in, sessions, and API keys live in
the [API reference](/api/overview) under the Auth tag.

### MCP server key

The MCP server accepts the same personal API key. See the
[MCP overview](/mcp/overview).

## Access gates

A credential gets you in. Two further gates apply:

* **Email verification.** Writes require a verified email address. Reads stay
  open, so an unverified user can still view the dashboard. An unverified
  write returns `403`.
* **Roles.** Some endpoints need the owner or admin role. Examples: stopping
  agent runs and selecting the platform AI model. The endpoint
  descriptions in the API reference name the required role.

## Accounts

* Sign-up is invite-only. An administrator sends the invitation, and the
  invited address picks its role at sign-up.
* The first account on a fresh install becomes the owner. The owner role is
  permanent and cannot be deleted.
* You can schedule deletion of your own account from the profile API. Owner
  accounts refuse deletion.

## Rate limits on auth routes

Better Auth applies its own limiter to `/api/auth/*`. Sign-in allows 3
attempts per 10 seconds. Sign-up allows 5 per minute. Verification email
resends allow 1 per cooldown window. See [Rate limits](/rate-limits).