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

# Getting started

> Enable Archie Auth, configure the password policy and token TTLs, and walk the full signup → verify → login flow.

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](/features/backend/app-services/authentication-providers/archie-auth/user-management), [Security](/features/backend/app-services/authentication-providers/archie-auth/security), and the [REST](/features/backend/app-services/authentication-providers/archie-auth/rest-api) / [GraphQL](/features/backend/app-services/authentication-providers/archie-auth/graphql-api) API references for the full surface.

## Enable Archie Auth

<Steps>
  <Step title="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.
  </Step>

  <Step title="Click Configure → Enable">
    Toggle **Enable** to activate Archie Auth for the **current environment**. Each environment must be enabled independently.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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](/features/backend/app-services/authentication-providers/archie-auth/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](/features/backend/app-services/authentication-providers/archie-auth/graphql-api).

### 1. Sign up

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](/features/backend/app-services/role-based-access) 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:

```bash theme={null}
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..."
  }'
```

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

## Disabling Archie Auth

If you outgrow Archie Auth or migrate to another provider:

<Steps>
  <Step title="Open the Archie Auth panel">
    Navigate to **App Services → Authentication Providers → Archie Auth**.
  </Step>

  <Step title="Click Disable">
    A confirmation dialog appears with an option to drop the `_auth_credentials` table.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="What's the cleanest way to seed admin users?">
    Use the GraphQL API with an admin token, or the [REST signup endpoint](/features/backend/app-services/authentication-providers/archie-auth/rest-api#post-auth-signup) 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.
  </Accordion>

  <Accordion title="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](/features/backend/app-services/authentication-providers/archie-auth/email-templates) for branding and sender configuration, and [SendGrid integration](/features/backend/integrations/sendgrid) if you're routing through SendGrid.
  </Accordion>

  <Accordion title="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](/features/backend/app-services/authentication-providers/archie-auth/security#key-rotation).
  </Accordion>
</AccordionGroup>