Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.autousers.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every /v1 request authenticates as one of four principals. The server resolves them in a fixed order; the first match wins.
OrderPathCarrierIdentityScopes
1SessionSupabase cookieUserimplicit (full)
2API keyAuthorization: Bearer ak_live_*API key → User + Teamexplicit allowlist
3OAuth 2.1Authorization: Bearer <jwt> (aud-bound)User + Teamexplicit (scope claim)
4Figma plugin JWTAuthorization: Bearer <jwt>Userimplicit (full)
session and figma-token principals have no scopes field — they authenticate as a real user and inherit that user’s team memberships. apikey and oauth principals must present an explicit scope per route or get 403 authorization_error: Missing required scope: ....
Scopes are layered on top of, not in place of, the route’s permission check. An ak_live_* key with evaluations:write scoped to team A still cannot write evaluations on team B — assertTeamAccess rejects the team mismatch.
Used by the dashboard at app.autousers.ai. Set automatically by Supabase Auth on sign-in. There is nothing for an integrator to do here. 
curl https://app.autousers.ai/api/v1/auth/whoami \
  --cookie "sb-...=..."

​
Path 2 — API key (ak_live_*)

The right choice for server-to-server, CI/CD, the CLI, and the MCP server. Mint at Settings → API keys; you’ll see the plaintext value once. 
curl https://app.autousers.ai/api/v1/auth/whoami \
  -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Properties:
  • Prefixed ak_live_; sha256-hashed at rest (never stored plaintext).
  • Bound to the team it was minted on. All requests act on that team.
  • Scopes are explicit and immutable for the life of the key. To change scopes, mint a new key and revoke the old one.
  • Optional expiry; default is no expiry.
  • Last-used IP and timestamp are recorded for audit.

​
Path 3 — OAuth 2.1 access token

Audience-bound HS256 JWT minted by /api/oauth/token after a user authorizes a third-party MCP app or SDK. Tokens are short-lived (≤15 minutes) and must carry an aud claim matching the resource server they are presented to (RFC 8707). A token minted for /mcp will not verify at /api/v1/*, and vice versa. 
curl https://app.autousers.ai/api/v1/auth/whoami \
  -H "Authorization: Bearer eyJ..."
Token payload: 
{
  "sub": "usr_clxq3...",
  "team": "team_clxq3...",
  "scope": "evaluations:read autousers:read",
  "aud": "https://app.autousers.ai/api/v1",
  "exp": 1714867200
}
Access tokens are stateless. Revoking the underlying refresh token stops future refreshes but does not invalidate access tokens already in flight; they expire naturally at their TTL. This is the standard OAuth 2.1 trade-off.

​
Path 4 — Figma plugin JWT

Issued by /api/auth/figma/* for the Autousers Figma plugin only. Stored in figma.clientStorage. 7-day expiry. HS256, signed with a secret distinct from the OAuth signing key — Figma JWTs cannot be replayed as OAuth tokens or vice versa. You will not need this unless you are forking the Figma plugin.

​
Scopes

Scopes are resource:action strings. Use the wildcard sparingly.
ScopeGrants
*Admin — every action on every resource family.
templates:readList, read templates / dimensions.
templates:writeCreate, update, delete templates / dimensions.
templates:*All template actions.
evaluations:readList, read evaluations and their nested resources.
evaluations:writeCreate, update, delete evaluations.
evaluations:*All evaluation actions.
autousers:readList, read autousers, calibration, runs.
autousers:writeCreate, update, delete autousers; trigger calibration.
autousers:*All autouser actions.
ratings:readList ratings on evaluations the caller can read.
ratings:writeSubmit, bulk-delete ratings.
ratings:*All rating actions.
When webhooks ship (see Changelog) three more scopes are added: webhooks:read, webhooks:write, events:read.
The literal scope is checked first, then the family wildcard (evaluations:*), then the admin wildcard (*).

​
Key rotation

Mint a new key with the same scopes, deploy it, then revoke the old key. 
# 1. Mint replacement
curl -X POST https://app.autousers.ai/api/v1/api-keys \
  --cookie "sb-...=..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-2026-q3", "scopes": ["evaluations:read", "evaluations:write"] }'

# 2. Update your secret store with the new key.

# 3. Revoke the old key.
curl -X DELETE https://app.autousers.ai/api/v1/api-keys/<old_key_id> \
  --cookie "sb-...=..."
/api/v1/api-keys/* is session-only. You cannot mint or revoke keys with another ak_live_* key — that prevents a leaked key from bootstrapping itself into permanence. Use the dashboard or a session cookie.

​
Best practices

  • Mint a separate key per environment (CI, staging, prod). Revoke blast radius is the key, not the account.
  • Use the narrowest scope that works. Reach for evaluations:read before evaluations:*, and * only for break-glass admin tooling.
  • Rotate keys annually or when an employee with key access leaves.
  • Set an expiry on keys you only need for a known window (a launch, a contractor engagement).
  • Never log the Authorization header. Never paste a key into a chat transcript or a screenshot.