Getting started

This page gets you from a blank project to a working signup / login flow against Archie Auth in a few minutes. After that, see User management, Security, and the REST / GraphQL API references for the full surface.

Enable Archie Auth

Open Authentication Providers

Navigate to App Services → Authentication Providers in the Backend Console. Archie Auth sits at the top of the list with a “Built-in” badge.

Click Configure → Enable

Toggle Enable to activate Archie Auth for the current environment. Each environment must be enabled independently.

Wait for setup to complete

On enable, Archie automatically:

Generates a 2048-bit RSA signing key pair (RS256) for JWT signing.
Generates a 2048-bit RSA encryption key pair (RSA-OAEP-256) for optional JWE encryption.
Encrypts both private keys with AES-GCM before storing them.
Creates the _auth_credentials table in the project database.
Registers the identity service with the GraphQL schema.

The Archie Auth panel now shows three tabs: Settings, Users, and API.

Configure the policy

The Settings tab is where you tune behavior. Defaults are sensible — you can leave most of it alone — but the configurable fields are:

General

Setting	Default	Description
Self-Signup	On	Whether anonymous visitors can register themselves.
Email Verification	On	Whether users must confirm their email before logging in.
Allowed Email Domains	empty	Optional allowlist of domains permitted to sign up.

Security policy

Setting	Default	Description
Password Min Length	8	Shortest password accepted.
Require Uppercase	Yes	At least one A–Z.
Require Lowercase	Yes	At least one a–z.
Require Digit	Yes	At least one 0–9.
Require Special Char	Yes	At least one of `!@#$%^&*` etc.
Max Failed Attempts	5	Failed logins before lockout. `0` disables.
Lock Duration	30 min	How long a locked account stays locked.

Token configuration

Setting	Default	Description
Access Token TTL	900 seconds (15 min)	Lifetime of an access token.
Refresh Token TTL	2,592,000 seconds (30 days)	Lifetime of a refresh token.
JWE Encryption	Off	Encrypt access token claims (turns 3-part JWS into 5-part JWE).

For the cryptographic background and JWE trade-off, see Security.

Quick test — the full auth flow

After enabling, exercise the public endpoints directly with curl. The same operations are available on the GraphQL API.

curl -X POST https://your-gateway.example.com/auth/signup \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master" \
  -d '{
    "email": "user@example.com",
    "password": "SecureP@ss1",
    "firstName": "John",
    "lastName": "Doe"
  }'

{
  "userId": "a1b2c3d4-...",
  "message": "Verification email sent"
}

The response is 201 Created. A 6-digit verification code lands in the user’s inbox.

2. Confirm the email

curl -X POST https://your-gateway.example.com/auth/confirm-signup \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master" \
  -d '{
    "email": "user@example.com",
    "code": "123456"
  }'

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

Confirming email returns the user logged in — you don’t need a separate login call after signup.

3. Log in

For users that confirmed earlier and need a fresh token:

curl -X POST https://your-gateway.example.com/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master" \
  -d '{
    "email": "user@example.com",
    "password": "SecureP@ss1"
  }'

The response is the same shape as confirm-signup — access token, refresh token, user object.

4. Use the access token

Send the access token as a Bearer token on subsequent API calls:

curl -X POST https://your-api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master" \
  -d '{ "query": "{ usersList { items { id email } } }" }'

The token is checked on every request. The carrier’s roles decide which fields and rows the response contains.

5. Refresh when the access token expires

Access tokens are short-lived by design. Refresh them with the refresh token:

curl -X POST https://your-gateway.example.com/auth/refresh-token \
  -H "Content-Type: application/json" \
  -H "X-Project-Id: your-project-id" \
  -H "environment: master" \
  -d '{
    "refreshToken": "dGhpcyBpcyBh..."
  }'

Refresh tokens are rotated on use. The previous refresh token is invalidated and a new one is returned in the response. Always store the new refresh token.

Disabling Archie Auth

If you outgrow Archie Auth or migrate to another provider:

Open the Archie Auth panel

Navigate to App Services → Authentication Providers → Archie Auth.

Click Disable

A confirmation dialog appears with an option to drop the _auth_credentials table.

Choose what happens to existing users

Keep the table — re-enabling later preserves the user list and credentials.
Drop the table — wipes the user list. Re-enabling creates a fresh table.

Disabling auth revokes all active refresh tokens immediately. Users will need to log in again after you re-enable.

FAQ

Why does the access token expire so fast?

Short-lived access tokens limit the blast radius of a stolen token. The refresh token (30 days by default) is the long-lived credential — it stays on the client and gets rotated on every use, so a leaked refresh token also gets invalidated quickly.

Can I bypass email verification during development?

Yes — toggle Email Verification off in the Settings tab for that environment. Users sign up and immediately get a usable session. Re-enable it before exposing the environment to real users.

What's the cleanest way to seed admin users?

Use the GraphQL API with an admin token, or the REST signup endpoint with the roleId field set to your admin role’s ID. Either way the user goes through the standard signup path so the _auth_credentials row is consistent.

What if my emails aren't being delivered?

The transport (SES or SMTP) is configured at the platform level. Check the user’s spam folder first. If consistently undelivered, see Email templates for branding and sender configuration, and SendGrid integration if you’re routing through SendGrid.

How do I rotate my signing key?

From the Settings tab or via the rotateAuthKeys mutation. Old keys are kept for a 1-hour grace period so in-flight tokens stay valid. See Security.

Home

Blueprint

Design

Frontend

Backend

Assets

Enable Archie Auth

Configure the policy

General

Security policy

Token configuration

Quick test — the full auth flow

2. Confirm the email

3. Log in

4. Use the access token

5. Refresh when the access token expires

Disabling Archie Auth

FAQ

​Enable Archie Auth

​Configure the policy

​General

​Security policy

​Token configuration

​Quick test — the full auth flow

​1. Sign up

​2. Confirm the email

​3. Log in

​4. Use the access token

​5. Refresh when the access token expires

​Disabling Archie Auth

​FAQ

Enable Archie Auth

Configure the policy

General

Security policy

Token configuration

Quick test — the full auth flow

1. Sign up

2. Confirm the email

3. Log in

4. Use the access token

5. Refresh when the access token expires

Disabling Archie Auth

FAQ