Authentication

API Keys

All authenticated requests use an API key passed in the Authorization header:

Authorization: Bearer aira_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ...

Key Format

API keys follow this format:

• Live keys: aira_live_ prefix — for production use
• Test keys: aira_test_ prefix — for development (coming soon)

Keys are 32+ random bytes (base58-encoded) after the prefix.

Key Security

• Keys are hashed with HMAC-SHA256 before storage. Aira never stores your plain key.
• Your full key is shown exactly once — at creation time. Save it immediately.
• If you lose a key, revoke it and create a new one.

Creating API Keys

Your first key is created automatically when you register. Create additional keys via the API:

curl -X POST https://api.airaproof.com/api/v1/api-keys \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

{
  "id": "key_01J8X...",
  "name": "Production Key",
  "key": "aira_live_newKeyShownOnlyOnce...",
  "key_prefix": "aira_live_newKeySho...",
  "scopes": ["cases:write", "receipts:read"],
  "created_at": "2026-03-14T10:00:00Z",
  "request_id": "req_..."
}

Listing Keys

List all keys for your organization (keys are masked):

curl https://api.airaproof.com/api/v1/api-keys \
  -H "Authorization: Bearer aira_live_xxxxx"

Revoking Keys

Revoke a compromised or unused key:

curl -X DELETE https://api.airaproof.com/api/v1/api-keys/{key_id} \
  -H "Authorization: Bearer aira_live_xxxxx"

Revocation is immediate and permanent. Revoked keys return 401 UNAUTHORIZED.

Rate Limits

All plans share a global rate limit of 60 requests per minute. Case run quotas vary by plan:

When you exceed a rate limit, the API returns 429 with a clear error:

{
  "error": "Too many requests",
  "code": "RATE_LIMIT_EXCEEDED",
  "request_id": "req_..."
}

Account Management

Leave Organization

Team members (non-owners) can leave their organization. This anonymizes personal data and deactivates the account:

curl -X POST https://api.airaproof.com/api/v1/auth/leave-org \
  -H "Authorization: Bearer <jwt_token>"

Transfer Ownership

Organization owners can transfer ownership to an admin:

curl -X POST https://api.airaproof.com/api/v1/team/transfer-ownership \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"target_user_id": "user_id_here"}'

Delete Organization

Organization owners can permanently delete the organization and all data:

curl -X DELETE https://api.airaproof.com/api/v1/auth/account \
  -H "Authorization: Bearer <jwt_token>"

Warning: Organization deletion is irreversible. All cases, receipts, API keys, team members, and audit logs are permanently removed.

Error Responses

All errors follow a consistent shape:

{
  "error": "Human-readable message",
  "code": "ERROR_CODE",
  "request_id": "req_..."
}