Password hashing
Passwords are hashed with bcrypt (cost factor 12) before storage. Plaintext passwords are never persisted. Bcrypt’s per-hash salt means identical passwords produce different hashes — rainbow tables are useless against the stored values.Password policy
Configurable per environment. Defaults:
Policy violations come back as an
array in the signup / reset response, so your UI can show targeted feedback (“password needs a special character”) rather than a generic error.
Token strategy
Archie Auth issues a two-tier token pair on every successful authentication:Access token
Sent on every API call as
Authorization: Bearer <token>. The short lifetime is deliberate — limits how long a stolen token is useful.
Refresh token
Sent only to
/auth/refresh-token. Always store the new refresh token from every refresh response — the previous one is invalidated immediately. Reusing a previously-rotated refresh token is detected and triggers a session-wide invalidation.
JWS vs. JWE
Two access-token formats. Pick based on whether the claims need to be confidential.JWS — signed, claims visible (default)
A standard 3-partheader.payload.signature JWT. Claims are readable to anyone who decodes the token; the signature prevents tampering. Validated with the public key from the JWKS endpoint.
This is the right default. Most applications can tolerate readable claims (subject, email, roles).
JWE — encrypted (opt-in)
A 5-part JWE string. Claims are encrypted and unreadable without the platform’s private decryption key. Built on top of JWS: tokens are signed first, then encrypted (nested JWT).
Enable JWE when claims contain sensitive information that must not be inspectable at the client or in logs, or when compliance mandates strict claim confidentiality.
Toggle JWE Encryption in the Archie Auth settings to enable, or call
configureProjectAuth with jweEnabled: true. Both formats are accepted on inbound requests, so you can flip the toggle without breaking in-flight tokens.
Key management
Two key pairs
Separate 2048-bit RSA key pairs for signing and encryption. Private keys are encrypted at rest with AES-GCM. Public signing keys are exposed at the standard JWKS endpoint:Per-environment keys
Each environment manages its own keys independently. A token signed instaging cannot be validated in master. That isolation is the security boundary — there’s no path by which a dev token bleeds into production traffic.
Key rotation
Rotate from the Settings tab or via therotateAuthKeys mutation. The flow:
- New key pairs are generated.
- Old public keys are kept for a 1-hour grace period, so existing tokens stay valid while clients pick up the new keys.
- New tokens are signed with the new keys immediately.
- After the grace period, old keys are dropped.
keyType accepts "signing", "encryption", or "both". Rotate signing keys regularly; rotate encryption keys when you suspect compromise or on a compliance schedule.
Rate limiting
Built-in protection on the public auth endpoints:
Exceeding any limit returns
429 Too Many Requests with a Retry-After header. Recovery is per-email (not per-IP) so a single attacker can’t burn the rate-limit budget for every user from one address.
Account lockout
After too many failed logins, an account is temporarily locked to defend against credential stuffing.
Locked accounts return
423 Locked with a lockedUntil timestamp on the next login attempt.
Token revocation
When a user logs out (or an admin force-logs them out), the access token is added to a distributed blacklist. The blacklist is checked on every request, so a revoked token is rejected before its natural expiry. Refresh tokens are invalidated synchronously — the database row is removed, so the next refresh attempt fails. There is no grace period on revoked refresh tokens.Verification code security
Email verification and password recovery codes:
Codes are single-use; on success they’re deleted. On lockout, the user (or an admin) can request a fresh code.
Authentication events
Archie Auth emits system events at key points in the lifecycle. Subscribe to them via custom functions or webhooks for audit logging, anomaly detection, or downstream sync.
Event payloads include environment, user ID, email, timestamp, and (for failures) the reason and originating IP.
FAQ
Should I enable JWE?
Should I enable JWE?
Most apps don’t need it — JWS signing is enough. Enable JWE if your access tokens carry sensitive claims you don’t want readable client-side or in logs, or if compliance mandates encrypted claims.
How often should I rotate keys?
How often should I rotate keys?
On a schedule that matches your threat model — every 90 days is a common cadence. Rotate immediately on any suspected compromise. Rotation is non-disruptive thanks to the 1-hour grace period.
Where do I tune rate limits and lockout?
Where do I tune rate limits and lockout?
Lockout (max attempts, lock duration) is configurable per environment via the Archie Auth Settings tab or
configureProjectAuth. Rate limits on the public auth endpoints are platform defaults — for tighter limits, put a Custom API in front with a per-route rate-limit policy.Can external services validate tokens without calling Archie?
Can external services validate tokens without calling Archie?
Yes — fetch the JWKS from
/auth/.well-known/jwks.json and verify locally. The endpoint is public, the response is cached for 5 minutes, and includes both the signing key (use=sig) and, when JWE is enabled, the encryption key (use=enc).What happens if a refresh token is reused?
What happens if a refresh token is reused?
Reuse is treated as a token-theft signal. The session is invalidated and all associated tokens are revoked. The legitimate user sees a forced re-login on their next refresh attempt.