Skip to main content
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:
API keys give the same access as your session. Keep them secret. If a key leaks, rotate it from Settings. The dashboard uses a browser session. Sign in through Better Auth:
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 under the Auth tag.

​
MCP server key

The MCP server accepts the same personal API key. See the 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.