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

# User management

> Block users, force logout, resend verification, and inspect login activity from the Archie Auth admin panel — or do all of it via the GraphQL admin API.

The **Users** tab in the Archie Auth panel is where you manage registered users in the current environment. Block accounts under investigation, force a logout after a security incident, resend verification when an email got lost, or just see who's signed up.

Every action available in the UI has a matching [GraphQL admin mutation](/features/backend/app-services/authentication-providers/archie-auth/graphql-api#admin-mutations) for programmatic use.

## The users table

| Column         | What it shows                                               |
| -------------- | ----------------------------------------------------------- |
| **Email**      | The user's registered address.                              |
| **Name**       | First + last name.                                          |
| **Status**     | One of Active, Unverified, Locked, or Disabled (see below). |
| **Last Login** | Timestamp of the most recent successful login.              |
| **Actions**    | Per-row admin controls.                                     |

Filter by email with the search box. Results paginate at 20 per page.

## User statuses

| Status         | What it means                                                                    |
| -------------- | -------------------------------------------------------------------------------- |
| **Active**     | Verified, not blocked. Can log in.                                               |
| **Unverified** | Signed up but hasn't confirmed email. Login blocked until verified.              |
| **Locked**     | Hit the failed-login threshold. Auto-unlocks after the configured lock duration. |
| **Disabled**   | Manually blocked by an admin. Stays disabled until unblocked.                    |

## Admin actions

### Block / unblock

| Action      | Effect                                                                                                      |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| **Block**   | Sets `disabled = true` on the credential record. Active sessions aren't terminated; new logins are refused. |
| **Unblock** | Clears `disabled`, restoring login access.                                                                  |

Use Block for investigations and account suspensions. To kick a blocked user out of an active session immediately, **Force Logout** them after blocking.

### Resend verification

If a user didn't receive (or lost) the verification code, resend it. A new 6-digit code is generated with a fresh 1-hour expiry. The previous code is invalidated.

### Force logout

Invalidates the user's refresh token. Their access token stays valid until natural expiry (15 minutes by default), but they can't refresh — so they'll be forced back to the login screen on the next refresh attempt.

For an instant kick-out, combine Force Logout with Block. The token blacklist on every request will reject the access token even before it expires.

### Force logout all

Revokes every user's refresh token in the current environment. Use after a security incident — a leaked signing key, a database breach, anything that requires forcing every user to re-authenticate.

The blast radius is intentionally environment-scoped: forcing logout in `master` doesn't touch `staging`.

## Per-environment scope

User management is scoped to the **current environment**. A user registered in `staging` is a different record from a user with the same email registered in `master`. Switching the environment selector changes the entire users table.

This separation is the point — it means dev and staging traffic doesn't pollute production user records, and a developer logging in to `staging` doesn't burn rate-limit budget in `master`.

## GraphQL admin API

Every dashboard action has a corresponding GraphQL mutation. Useful for scripted user-management — bulk-revoke after an incident, sync user state from another system, or build your own admin UI.

| Mutation / Query          | Purpose                                                        |
| ------------------------- | -------------------------------------------------------------- |
| `adminListCredentials`    | List every registered user with status, email, and last-login. |
| `adminToggleUserStatus`   | Block or unblock a user.                                       |
| `adminResendVerification` | Send a fresh verification code to a user.                      |
| `adminForceLogout`        | Force-logout a specific user.                                  |
| `adminForceLogoutAll`     | Force-logout every user in the current environment.            |

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

Full request/response shapes are in the [Archie Auth GraphQL API reference](/features/backend/app-services/authentication-providers/archie-auth/graphql-api#admin-mutations).

## Permissions

Admin operations require admin-level authentication — typically a user with the `admin` role or an [API key](/features/backend/settings/api-keys) attached to that role. Define the role in [Role-Based Access](/features/backend/app-services/role-based-access) and grant it the system permissions needed for the admin mutations.

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between Block and Force Logout?">
    Block prevents future logins. Force Logout terminates the current session by invalidating the refresh token. Combine them for an instant kick-out: Block stops new logins; Force Logout cuts the live session.
  </Accordion>

  <Accordion title="A user is locked but the lock duration is too long — how do I unlock them?">
    Block then Unblock the user. That clears the lockout state. Alternatively, run a successful password reset — the recovery flow clears the lockout on success.
  </Accordion>

  <Accordion title="Does Force Logout All affect API keys?">
    No — API keys are managed separately under [Backend → Settings → API Keys](/features/backend/settings/api-keys) and aren't touched by user-session operations. Rotate compromised API keys there.
  </Accordion>

  <Accordion title="Can I delete a user instead of disabling them?">
    Use the Data Model's `users` table or `_auth_credentials` to delete the row. Hard deletion removes the credential entirely; disabling preserves history. Most teams disable rather than delete to keep an audit trail.
  </Accordion>

  <Accordion title="How do I bulk-export the user list?">
    Use `adminListCredentials` over the [GraphQL API](/features/backend/app-services/authentication-providers/archie-auth/graphql-api), or query the `_auth_credentials` table directly via the [Data Viewer](/features/backend/data-model/data-viewer) or [SQL Playground](/features/backend/sql-playground).
  </Accordion>
</AccordionGroup>