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

# GraphQL API

> GraphQL mutations and queries for Archie Auth — signup, login, password reset, refresh, admin operations, and configuration.

Archie Auth exposes the full auth surface through the platform's unified [GraphQL API](/features/backend/graphql-api-explorer/overview). This page is the operation reference — every mutation and query, with example payloads.

For the equivalent HTTP endpoints, see the [REST API reference](/features/backend/app-services/authentication-providers/archie-auth/rest-api).

## Required headers

| Header          | Required                     | Description                               |
| --------------- | ---------------------------- | ----------------------------------------- |
| `Authorization` | For authenticated operations | Bearer access token.                      |
| `X-Project-Id`  | Yes                          | Your project identifier.                  |
| `environment`   | Yes                          | Target environment name (e.g., `master`). |

Auth operations route through the API Manager directly to the identity service — they don't pass through the regular GraphQL resolver layer, but they appear as standard GraphQL operations to the client.

## User mutations

### `authSignup`

Register a new user account.

```graphql theme={null}
mutation {
  authSignup(input: {
    email: "user@example.com"
    password: "SecureP@ss1"
    firstName: "John"
    lastName: "Doe"
  }) {
    userId
    message
  }
}
```

Returns a `userId` and a confirmation message. A verification email is sent if email verification is enabled in the project settings.

### `authLogin`

Authenticate with email and password.

```graphql theme={null}
mutation {
  authLogin(input: {
    email: "user@example.com"
    password: "SecureP@ss1"
  }) {
    accessToken
    refreshToken
    user {
      id
      email
      firstName
      lastName
      roles
    }
  }
}
```

Returns the access/refresh token pair and the user object including assigned roles.

### `authConfirmSignup`

Confirm an email with the 6-digit verification code.

```graphql theme={null}
mutation {
  authConfirmSignup(input: {
    email: "user@example.com"
    code: "123456"
  }) {
    accessToken
    refreshToken
    user {
      id
      email
      firstName
      lastName
    }
  }
}
```

On success the user is logged in immediately — no follow-up `authLogin` call needed.

### `authRecoverPassword`

Request a password recovery email. Always returns success to prevent email enumeration.

```graphql theme={null}
mutation {
  authRecoverPassword(input: {
    email: "user@example.com"
  }) {
    message
  }
}
```

### `authResetPassword`

Reset a password using the recovery code from the recovery email.

```graphql theme={null}
mutation {
  authResetPassword(input: {
    email: "user@example.com"
    newPassword: "NewSecureP@ss2"
    code: "654321"
  }) {
    message
  }
}
```

A successful reset clears any active account lockout.

### `authRefreshToken`

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

```graphql theme={null}
mutation {
  authRefreshToken(input: {
    refreshToken: "base64-encoded-token..."
  }) {
    accessToken
    refreshToken
  }
}
```

<Warning>
  Refresh tokens are rotated on every use — the previous one is invalidated. Always store the new refresh token from the response.
</Warning>

## Admin mutations

These mutations require admin-level authentication. Attach the `admin` role (or another role with the necessary permissions) to a user or [API key](/features/backend/settings/api-keys) and use that token to call them.

### `adminResendVerification`

Re-send the verification code to a specific user.

```graphql theme={null}
mutation {
  adminResendVerification(input: {
    email: "user@example.com"
  }) {
    success
    message
  }
}
```

### `adminForceLogout`

Invalidate the refresh token of a specific user. Their access token continues to work until natural expiry; the next refresh fails.

```graphql theme={null}
mutation {
  adminForceLogout(input: {
    userId: "a1b2c3d4-e5f6-..."
  }) {
    success
    message
  }
}
```

### `adminForceLogoutAll`

Invalidate every refresh token in the current environment. Use after a security incident.

```graphql theme={null}
mutation {
  adminForceLogoutAll {
    success
    message
  }
}
```

### `adminToggleUserStatus`

Block or unblock a user account. Blocked users cannot log in.

```graphql theme={null}
mutation {
  adminToggleUserStatus(input: {
    userId: "a1b2c3d4-e5f6-..."
    disabled: true
  }) {
    success
    message
  }
}
```

## Admin queries

### `adminListCredentials`

List every registered credential in the current environment.

```graphql theme={null}
query {
  adminListCredentials {
    id
    userId
    email
    emailVerified
    disabled
    lastLoginAt
    failedAttempts
    lockedUntil
    createdAt
  }
}
```

Useful for building admin UIs, exporting user lists, or syncing user state into another system.

## Auth configuration mutations

These manage the auth setup for the current project + environment. They require admin-level authentication.

### `enableProjectAuth`

Enable Archie Auth for the current environment. Generates the signing and encryption key pairs, creates the `_auth_credentials` table, and registers the identity service.

```graphql theme={null}
mutation {
  enableProjectAuth {
    success
    message
  }
}
```

### `disableProjectAuth`

Disable Archie Auth. Optionally drop the `_auth_credentials` table — keep it to preserve user records if you intend to re-enable later.

```graphql theme={null}
mutation {
  disableProjectAuth(input: {
    dropTable: false
  }) {
    success
    message
  }
}
```

Disabling revokes all active refresh tokens.

### `configureProjectAuth`

Update auth settings for the current environment. Every field is optional — pass only the fields you want to change.

```graphql theme={null}
mutation {
  configureProjectAuth(input: {
    selfSignup: true
    emailVerification: true
    jweEnabled: false
    passwordPolicy: {
      minLength: 10
      requireUppercase: true
      requireLowercase: true
      requireDigit: true
      requireSpecial: true
    }
    accountLockout: {
      maxAttempts: 5
      lockDuration: 1800
    }
    tokenTTL: {
      accessToken: 900
      refreshToken: 2592000
    }
    emailTemplates: {
      verification: {
        subject: "Verify your email"
        body: "Your code is {{otp}}"
      }
      recovery: {
        subject: "Reset your password"
        body: "Your recovery code is {{otp}}"
      }
    }
    emailBranding: {
      logoUrl: "https://example.com/logo.png"
      companyName: "My Company"
      companyWebsite: "https://example.com"
      senderName: "My Company Auth"
    }
  }) {
    success
  }
}
```

For background on each policy option, see [Security](/features/backend/app-services/authentication-providers/archie-auth/security). For email customization, see [Email templates](/features/backend/app-services/authentication-providers/archie-auth/email-templates).

### `rotateAuthKeys`

Rotate signing and/or encryption keys. Old keys are kept for a 1-hour grace period so existing tokens stay valid through the rollover.

```graphql theme={null}
mutation {
  rotateAuthKeys(input: {
    keyType: "both"
  }) {
    success
    message
  }
}
```

`keyType` accepts `"signing"`, `"encryption"`, or `"both"` (default `"both"`).

## Configuration query

### `getProjectAuth`

Read the current auth configuration for the active environment.

```graphql theme={null}
query {
  getProjectAuth {
    enabled
    selfSignup
    emailVerification
    jweEnabled
    passwordPolicy {
      minLength
      requireUppercase
      requireLowercase
      requireDigit
      requireSpecial
    }
    accountLockout {
      maxAttempts
      lockDuration
    }
    tokenTTL {
      accessToken
      refreshToken
    }
    emailBranding {
      logoUrl
      companyName
      companyWebsite
      senderName
    }
  }
}
```

## FAQ

<AccordionGroup>
  <Accordion title="Why don't admin operations show up in the GraphQL Documentation panel?">
    Admin operations require admin-level authentication. The Documentation panel reflects the schema available to your current token — if you're logged in with a non-admin role, admin operations are filtered out. Switch to an admin token to see them.
  </Accordion>

  <Accordion title="Can I run these operations from the GraphQL API Explorer?">
    Yes. The Explorer authenticates as your workspace user, so all admin operations are available without extra setup. Outside the Explorer, attach an admin token (or API key) on each request.
  </Accordion>

  <Accordion title="Are there subscriptions for auth events?">
    Auth events are emitted as system events — `auth.user.registered`, `auth.user.login.success`, etc. — but not as GraphQL subscriptions. Consume them via webhooks or custom functions. See [Security → Authentication events](/features/backend/app-services/authentication-providers/archie-auth/security#authentication-events).
  </Accordion>

  <Accordion title="What's the right way to handle a refresh-token rotation race?">
    Single-flight the refresh on the client — only one in-flight refresh at a time. If two tabs trigger refresh simultaneously, the second one fails with `AUTH_TOKEN_INVALID` because the first already rotated the token. Coordinate via a shared lock or a single-tab refresh worker.
  </Accordion>

  <Accordion title="How do I configure the password policy without the dashboard?">
    Call `configureProjectAuth` with the `passwordPolicy` field set. Useful for codifying configuration alongside infra-as-code.
  </Accordion>
</AccordionGroup>