REST API

Archie Auth exposes its full surface as REST endpoints on the platform gateway. Use them when you’d rather call HTTP directly than go through GraphQL — anywhere a curl or a thin HTTP client is the right tool. For the equivalent GraphQL operations, see the GraphQL API reference.

Required headers

Header	Required	Default	Description
`X-Project-Id`	Yes	—	Your project identifier.
`environment`	No	`master`	Target environment name.
`Content-Type`	Yes	—	`application/json`.
`Authorization`	Protected endpoints only	—	`Bearer <accessToken>`.

Base URL: https://your-gateway.example.com

Public endpoints

These don’t require authentication — they’re the way unauthenticated visitors enter the system. Register a new user account. Request:

{
  "email": "user@example.com",
  "password": "SecureP@ss1",
  "firstName": "John",
  "lastName": "Doe",
  "roleId": "optional-role-id"
}

Responses:

Status	Body	When
201	`{ "userId": "uuid", "message": "Verification email sent" }`	Created.
400	`{ "error": "VALIDATION_ERROR", "violations": [...] }`	Invalid input or weak password.
409	`{ "error": "AUTH_EMAIL_EXISTS" }`	Email already registered.
404	`{ "error": "AUTH_NOT_CONFIGURED" }`	Auth not enabled for this project + environment.
429	`{ "error": "RATE_LIMIT_EXCEEDED" }`	Too many signups (10/min per IP).

If email verification is disabled, the user is auto-verified and can log in immediately. Authenticate and receive an access/refresh token pair. Request:

{
  "email": "user@example.com",
  "password": "SecureP@ss1"
}

Successful response (200):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "base64-encoded-token...",
  "user": {
    "id": "a1b2c3d4-e5f6-...",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "roles": ["Member"]
  }
}

Error responses:

Status	Body	When
401	`{ "error": "AUTH_INVALID_CREDENTIALS" }`	Wrong email or password.
403	`{ "error": "AUTH_EMAIL_NOT_VERIFIED" }`	Email not yet confirmed.
423	`{ "error": "AUTH_ACCOUNT_LOCKED", "lockedUntil": "..." }`	Locked from failed attempts.
429	`{ "error": "RATE_LIMIT_EXCEEDED" }`	Too many logins (20/min per IP).

When JWE encryption is enabled, the accessToken is a 5-part JWE string instead of a 3-part JWS. Both formats are accepted on inbound requests. Confirm an email with the 6-digit code. Request:

{
  "email": "user@example.com",
  "code": "123456"
}

Responses:

Status	Body	When
200	`{ "accessToken": "...", "refreshToken": "...", "user": {...} }`	Confirmed and logged in.
400	`{ "error": "AUTH_INVALID_CODE" }`	Code wrong, expired, or attempt limit hit.

Codes expire after 1 hour. Up to 5 attempts are allowed before the code is invalidated.

POST `/auth/recover-password`

Request a password recovery email. Always returns 200, regardless of whether the email exists, to prevent enumeration. Request:

{
  "email": "user@example.com"
}

Response (always 200):

{
  "message": "If account exists, recovery email sent"
}

Rate-limited to 5 / minute per email.

POST `/auth/reset-password`

Reset a password using the recovery code. Request:

{
  "email": "user@example.com",
  "newPassword": "NewSecureP@ss2",
  "code": "654321"
}

Responses:

Status	Body	When
200	`{ "message": "Password reset successfully" }`	Updated.
400	`{ "error": "AUTH_INVALID_CODE" }`	Code wrong or expired.

A successful reset clears any active account lockout.

POST `/auth/refresh-token`

Exchange a refresh token for a new access/refresh pair. Request:

{
  "refreshToken": "base64-encoded-token..."
}

Responses:

Status	Body	When
200	`{ "accessToken": "...", "refreshToken": "..." }`	New token pair.
401	`{ "error": "AUTH_TOKEN_INVALID" }`	Invalid or already-used refresh token.

Refresh tokens rotate on every use. The previous refresh token is invalidated; store the new one from the response. Reusing an old refresh token returns AUTH_TOKEN_INVALID and triggers a session-wide invalidation as a token-theft signal.

GET `/auth/.well-known/jwks.json`

Public JWKS endpoint for external services validating Archie-issued tokens. No authentication required. Response (200):

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "abc12345",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

When JWE encryption is enabled, two keys are returned — one for signing and one for encryption:

{
  "keys": [
    {
      "kty": "RSA", "kid": "abc12345", "use": "sig", "alg": "RS256", "n": "...", "e": "AQAB"
    },
    {
      "kty": "RSA", "kid": "enc-def67890", "use": "enc", "alg": "RSA-OAEP-256", "n": "...", "e": "AQAB"
    }
  ]
}

The response is cached in-memory for 5 minutes. External services should refresh on kid mismatch.

Protected endpoints

Require Authorization: Bearer <accessToken>.

POST `/auth/logout`

Revoke the current access token and invalidate the associated refresh token.

curl -X POST https://your-gateway.example.com/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master"

Responses:

Status	Body	When
200	`{ "message": "Logged out successfully" }`	Token revoked.
401	`{ "error": "AUTH_TOKEN_INVALID" }`	Missing or invalid token.

Revoked tokens are tracked in a distributed blacklist until their natural expiry, so re-presenting the access token after logout fails with 401.

Error codes reference

Code	HTTP	Meaning
`AUTH_EMAIL_EXISTS`	409	Email already registered.
`AUTH_INVALID_CREDENTIALS`	401	Wrong email or password.
`AUTH_EMAIL_NOT_VERIFIED`	403	Email not yet confirmed.
`AUTH_ACCOUNT_LOCKED`	423	Too many failed attempts; account temporarily locked.
`AUTH_INVALID_CODE`	400	Verification or recovery code wrong, expired, or out of attempts.
`AUTH_TOKEN_EXPIRED`	401	Access token has expired.
`AUTH_TOKEN_INVALID`	401	Token malformed, revoked, or tampered.
`AUTH_NOT_CONFIGURED`	404	Auth not enabled for this project + environment.
`RATE_LIMIT_EXCEEDED`	429	Too many requests; honor `Retry-After`.
`VALIDATION_ERROR`	400	Request body validation failed (see `violations`).

Rate limits

Endpoint	Limit	Scope
`POST /auth/signup`	10 / minute	Per IP
`POST /auth/login`	20 / minute	Per IP
`POST /auth/recover-password`	5 / minute	Per email

429 responses include a Retry-After header indicating seconds to wait.

FAQ

Why does `/auth/recover-password` always return 200?

To prevent email enumeration. If the response distinguished “exists” from “doesn’t exist”, an attacker could probe a list of emails and learn which are registered. Returning 200 either way removes that signal.

What's the safe way to validate tokens at the edge?

Fetch the JWKS from /auth/.well-known/jwks.json and validate signatures locally. Cache the JWKS on your edge service; refresh on kid mismatch (which signals key rotation). Don’t call Archie on every request to validate.

My token validates locally but Archie rejects it on the API — why?

Most likely a revocation. Archie checks a distributed token blacklist on every request, so logged-out and force-logged-out tokens fail even if the signature is valid. The local-only validation can’t see the blacklist.

How do I handle 423 Account Locked?

Surface a clear “account temporarily locked” message and either show the countdown from lockedUntil or offer a password reset link — a successful reset clears the lockout.

Can I rate-limit more aggressively for my own use case?

Put a Custom API in front of /auth/login with a tighter rate-limit policy. The auth endpoint defaults are platform-wide; per-route Custom API config lets you go stricter.

Home

Blueprint

Design

Frontend

Backend

Assets

Required headers

Public endpoints

POST `/auth/recover-password`

POST `/auth/reset-password`

POST `/auth/refresh-token`

GET `/auth/.well-known/jwks.json`

Protected endpoints

POST `/auth/logout`

Error codes reference

Rate limits

FAQ

​Required headers

​Public endpoints

​POST /auth/signup

​POST /auth/login

​POST /auth/confirm-signup

​POST /auth/recover-password

​POST /auth/reset-password

​POST /auth/refresh-token

​GET /auth/.well-known/jwks.json

​Protected endpoints

​POST /auth/logout

​Error codes reference

​Rate limits

​FAQ

Required headers

Public endpoints

POST `/auth/signup`

POST `/auth/login`

POST `/auth/confirm-signup`

POST `/auth/recover-password`

POST `/auth/reset-password`

POST `/auth/refresh-token`

GET `/auth/.well-known/jwks.json`

Protected endpoints

POST `/auth/logout`

Error codes reference

Rate limits

FAQ