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

1

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

Click Configure → Enable

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

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

SettingDefaultDescription
Self-SignupOnWhether anonymous visitors can register themselves.
Email VerificationOnWhether users must confirm their email before logging in.
Allowed Email DomainsemptyOptional allowlist of domains permitted to sign up.

​
Security policy

SettingDefaultDescription
Password Min Length8Shortest password accepted.
Require UppercaseYesAt least one A–Z.
Require LowercaseYesAt least one a–z.
Require DigitYesAt least one 0–9.
Require Special CharYesAt least one of !@#$%^&* etc.
Max Failed Attempts5Failed logins before lockout. 0 disables.
Lock Duration30 minHow long a locked account stays locked.

​
Token configuration

SettingDefaultDescription
Access Token TTL900 seconds (15 min)Lifetime of an access token.
Refresh Token TTL2,592,000 seconds (30 days)Lifetime of a refresh token.
JWE EncryptionOffEncrypt 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.

​
1. Sign up

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:
1

Open the Archie Auth panel

Navigate to App Services → Authentication Providers → Archie Auth.
2

Click Disable

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

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

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