Authentication

How does Areev authenticate requests?

Areev attaches an AuthIdentity (principal, scopes, auth method) to every request. Pass an API key on every call as Authorization: Bearer ar_...; for browser-based access, sign in through the Console and Areev exchanges your session for a short-lived token.

The request pipeline applies middleware in order: Request → CORS → RateLimit → AuthLayer → AI Disclosure → Handler. Public endpoints (/api/health, /api/config, /.well-known/*, /api/auth/oauth/*, /api/auth/register, /api/auth/login, /api/auth/verify-email, /api/billing/webhooks/*) bypass authentication entirely.

import requests

resp = requests.get("https://acme.areev.ai/api/memories", headers={
    "Authorization": "Bearer ar_7f3a9bc2d1e4..."
})

GET /api/memories HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer ar_7f3a9bc2d1e4...

How do API keys work?

API keys carry an ar_ prefix (admin-scoped, 67 chars: ar_ + 64 hex random bytes) or ap_ prefix (project-scoped). Keys are SHA-256 hashed at rest — Areev never holds reversible credentials on disk. The raw key is returned exactly once at creation time.

Manage keys through three endpoints: POST /api/auth/keys (create, returns the raw key once), GET /api/auth/keys (list with prefix only, no secrets), and DELETE /api/auth/keys/{key_id} (revoke). Creating a key requires admin scope and accepts a principal, name, and scopes array. Every downstream operation is attributed to the key’s principal in the audit trail.

resp = requests.post("https://acme.areev.ai/api/auth/keys",
    headers={"Authorization": "Bearer <admin-token>"},
    json={"name": "my-service", "principal": "service:my-app", "scopes": ["read", "write"]}
)
raw_key = resp.json()["raw_key"]  # ar_... — shown once

curl -X POST https://acme.areev.ai/api/auth/keys \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"name":"my-service","principal":"service:my-app","scopes":["read","write"]}'

You can also create and revoke keys from the API Keys page (/keys in the Console) without writing any code.

How does SSO work?

Connect an OIDC identity provider through the Console under Settings → SSO. Areev validates JWT bearer tokens against the provider’s JWKS for signature verification and maps the configured claim (default: email) to the principal identifier.

Principals follow a consistent format across auth methods: the stored principal for API keys (e.g., service:atmatic-prod) and user:{claim} for OIDC (e.g., user:john@example.com). Areev maps each principal into a unified AuthIdentity struct, so authorization and audit trail entries work identically regardless of how the request authenticated.

GET /api/memories HTTP/1.1
Host: acme.areev.ai
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

How are authentication events audited?

All authentication events are recorded in the hash-chained audit trail with dedicated event types. Areev logs 21 auth.* event types: 11 cover the standard user lifecycle (login through account deletion), and 10 cover break-glass / emergency-contact flows used for incident response and operator escalation. SIEM ingestion and compliance reports must consume both groups.

In the cloud and on-prem builds the full set is enabled. In a custom build without the auth feature flag only two events ship — auth.bootstrap_admin_key.generated and auth.break_glass_access — because the remaining 19 belong to login / OAuth / emergency-contact flows that the auth module owns.

The audit trail captures auth.login, auth.register, auth.logout, auth.refresh, auth.password_change, auth.password_reset, auth.failed_login, auth.oauth_link, auth.oauth_unlink, auth.org_switch, and auth.account_deleted. Failed login attempts are tracked for SOC 2 CC7.2 (security incident monitoring) and HIPAA 164.312(b) (audit controls) compliance. Each event includes the pseudonymized actor identity, timestamp, and hash chain link, making the record tamper-evident.

auth.login            User logged in via OAuth or email/password
auth.register         New user registered
auth.logout           User logged out (refresh token revoked)
auth.refresh          JWT token refreshed
auth.password_change  User changed their password
auth.password_reset   User reset their password via email flow
auth.failed_login     Failed login attempt (SOC 2 CC7.2, HIPAA 164.312(b))
auth.oauth_link       OAuth provider linked to account
auth.oauth_unlink     OAuth provider unlinked from account
auth.org_switch       Organization context switched (from/to org, role change)
auth.account_deleted  User account deleted (GDPR Art. 17 right-to-erasure)

Break-glass and emergency-contact events

Ten additional auth.* events cover the bootstrap admin key, break-glass operator access, and the emergency-contact / escalation-code workflow. These are high-signal for SIEM alerting — every occurrence is operator-initiated and reviewed.

auth.bootstrap_admin_key.generated   First-run admin key minted at cluster bootstrap
auth.break_glass_access              Operator invoked break-glass to access an org without standard auth
auth.emergency_contact.designated    Org owner designated an emergency contact
auth.emergency_contact.removed       Emergency contact removed by org owner
auth.emergency_contact.acknowledged  Emergency contact acknowledged a pending escalation
auth.emergency_contact.updated       Emergency contact details updated
auth.escalation_code.generated       Escalation code minted (challenge for break-glass grant)
auth.break_glass_grant.created       Break-glass grant created after escalation code redeemed
auth.break_glass_grant.revoked       Active break-glass grant revoked
auth.break_glass_grant.reviewed      Break-glass grant reviewed post-use (compliance close-out)

Related

• Audit Trail: All auth events are audit-logged
• Key Management: How API key material is protected at rest
• SOC 2: Access control requirements (CC6.1, CC6.3)