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.

Archie Auth exposes the full auth surface through the platform’s unified GraphQL API. This page is the operation reference — every mutation and query, with example payloads. For the equivalent HTTP endpoints, see the REST API reference.

​
Required headers

HeaderRequiredDescription
AuthorizationFor authenticated operationsBearer access token.
X-Project-IdYesYour project identifier.
environmentYesTarget 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. 
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. 
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. 
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. 
mutation {
  authRecoverPassword(input: {
    email: "user@example.com"
  }) {
    message
  }
}

​
authResetPassword

Reset a password using the recovery code from the recovery email. 
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. 
mutation {
  authRefreshToken(input: {
    refreshToken: "base64-encoded-token..."
  }) {
    accessToken
    refreshToken
  }
}
Refresh tokens are rotated on every use — the previous one is invalidated. Always store the new refresh token from the response.

​
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 and use that token to call them.

​
adminResendVerification

Re-send the verification code to a specific user. 
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. 
mutation {
  adminForceLogout(input: {
    userId: "a1b2c3d4-e5f6-..."
  }) {
    success
    message
  }
}

​
adminForceLogoutAll

Invalidate every refresh token in the current environment. Use after a security incident. 
mutation {
  adminForceLogoutAll {
    success
    message
  }
}

​
adminToggleUserStatus

Block or unblock a user account. Blocked users cannot log in. 
mutation {
  adminToggleUserStatus(input: {
    userId: "a1b2c3d4-e5f6-..."
    disabled: true
  }) {
    success
    message
  }
}

​
Admin queries

​
adminListCredentials

List every registered credential in the current environment. 
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. 
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. 
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. 
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. For email customization, see 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. 
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. 
query {
  getProjectAuth {
    enabled
    selfSignup
    emailVerification
    jweEnabled
    passwordPolicy {
      minLength
      requireUppercase
      requireLowercase
      requireDigit
      requireSpecial
    }
    accountLockout {
      maxAttempts
      lockDuration
    }
    tokenTTL {
      accessToken
      refreshToken
    }
    emailBranding {
      logoUrl
      companyName
      companyWebsite
      senderName
    }
  }
}

​
FAQ

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.
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.
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.
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.
Call configureProjectAuth with the passwordPolicy field set. Useful for codifying configuration alongside infra-as-code.