Getting started

Authentication

The management API is authenticated with a Personal Access Token (PAT). A PAT inherits the identity of the user who issued it, and is the only credential the API accepts.

Overview#

A Personal Access Token is a long-lived bearer token bound to your user account. Each user can have at most one PAT at a time — issuing a new one immediately invalidates the previous one, which doubles as the rotation flow.

PATs are stored hashed (SHA-256) at rest. The plaintext is shown to you exactly once, at the moment of issuance, and is unrecoverable after that. If you lose your token, rotate it from the dashboard.

Issue a token#

PATs are issued from the dashboard, not from the API. This is intentional: an attacker who steals a PAT must not be able to mint additional tokens or rotate the one they hold.

  • Sign in to your AIronClaw dashboard and open Profile.
  • Click Generate Personal Access Token.
  • Copy the token (it starts with aifw_pat_) and store it in a secret manager. The page will not show it again.
Treat as a password

A PAT grants the same access as your dashboard session, minus the ability to rotate itself or change 2FA. Keep it out of git, CI logs and shared chat.

Use the token#

Send the PAT in the Authorization header on every request. Cookies are not consulted when a Bearer header is present — the two channels are mutually exclusive.

curl https://app.aironclaw.com/api/profile \
  -H "Authorization: Bearer $AIFW_PAT"

Rotate a token#

Re-issuing a token from the dashboard automatically invalidates the previous one. There is no API endpoint for rotation: the route (POST /api/profile/token) is session-only by design, so a leaked PAT cannot be used to spawn a fresh one.

  • Open Profile.
  • Click Rotate Personal Access Token.
  • Copy the new token. Update every system that was using the old one — the old token returns 401 immediately after rotation.

Revoke a token#

To revoke without issuing a replacement, delete the token from the dashboard. Revocation takes effect immediately; in-flight requests may still complete but no new request will authenticate.

Scope & limits#

A PAT is account-scoped: it can read and modify any resource owned by the user who issued it. There is no per-resource scoping at this time. If you need narrower access, run AIronClaw automations as a dedicated service account user with only the resources they should see.

The following endpoints reject PATs and require a dashboard session:

  • POST /api/profile/token, GET /api/profile/token — token rotation and existence check.
  • /api/2fa/setup, /api/2fa/verify, /api/2fa/disable, /api/2fa/challenge — 2FA lifecycle.
  • /api/auth/* — NextAuth session endpoints.

Calling these with a PAT returns 403 Forbidden.

Session vs. PAT#

The dashboard authenticates via a NextAuth cookie session. The management API accepts either a session cookie (when called from the dashboard origin) or a PAT (when called from anywhere). They are mutually exclusive on a single request: if a Bearer header is present, the cookie is ignored even if invalid.

MFA gating

A session that requires 2FA but has not yet completed the challenge cannot call API endpoints — it gets 401 MFA required. PATs are not subject to this gate, because they are issued by an already-MFA-verified session at creation time.

Best practices#

  • Store the PAT in a secret manager (AWS Secrets Manager, Vault, Doppler, GitHub Encrypted Secrets). Never commit it.
  • Use different usersfor different automation domains (e.g. one user for Terraform, one for the audit pipeline). Rotating one PAT then doesn't require redeploying the others.
  • Rotate on a schedule (90 days is a sensible default) and on every offboarding event for users who held the token.
  • Watch the Logs APIfor unexpected calling patterns. Every request via PAT is logged with the calling user's email.