Skip to main content

Documentation Index

Fetch the complete documentation index at: https://archie.com/docs/llms.txt

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

This page is the security reference for Archie Auth — the cryptography under the hood, the rate-limit and lockout defaults, and how to rotate keys without taking users offline.

​
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:
RuleDefault
Minimum length8 characters
Uppercase letterRequired
Lowercase letterRequired
DigitRequired
Special characterRequired
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

PropertyValue
FormatJWT
Signing algorithmRS256 (RSA + SHA-256)
Default TTL15 minutes
Claimsiss, sub (userId), aud (projectId), exp, iat, email, roles[], environment
Sent on every API call as Authorization: Bearer <token>. The short lifetime is deliberate — limits how long a stolen token is useful.

​
Refresh token

PropertyValue
FormatCryptographically random opaque string
Default TTL30 days
RotationEach use issues a new refresh token and invalidates the previous one
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-part header.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).
AlgorithmUsed for
RSA-OAEP-256Key wrapping.
A256GCMContent encryption.
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: 
GET https://your-gateway.example.com/auth/.well-known/jwks.json
External services (microservices, edge workers, anything that needs to validate Archie-issued tokens locally) can fetch the JWKS and verify tokens without calling Archie.

​
Per-environment keys

Each environment manages its own keys independently. A token signed in staging 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 the rotateAuthKeys mutation. The flow:
  1. New key pairs are generated.
  2. Old public keys are kept for a 1-hour grace period, so existing tokens stay valid while clients pick up the new keys.
  3. New tokens are signed with the new keys immediately.
  4. After the grace period, old keys are dropped.
mutation {
  rotateAuthKeys(input: { keyType: "both" }) {
    success
    message
  }
}
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:
EndpointLimitScope
POST /auth/signup10 / minutePer IP
POST /auth/login20 / minutePer IP
POST /auth/recover-password5 / minutePer email
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.
SettingDefault
Max Failed Attempts5
Lock Duration30 minutes
Reset on SuccessYes — counter resets on the next successful login.
Reset on Password ChangeYes — counter and lock state both clear after password reset.
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:
PropertyValue
Format6-digit numeric
Expiry1 hour
Max attempts5 before the code is invalidated
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.
EventWhen it fires
auth.user.registeredSuccessful signup.
auth.user.login.successSuccessful login.
auth.user.login.failedFailed login (wrong password, account state, etc.).
auth.user.logoutLogout (manual or admin force-logout).
auth.user.password.changedPassword updated.
auth.user.password.recoveryPassword recovery flow initiated.
auth.user.email.verifiedEmail confirmed.
auth.user.lockedAccount locked due to failed attempts.
Event payloads include environment, user ID, email, timestamp, and (for failures) the reason and originating IP.

​
FAQ

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.
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.
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.
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).
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.