Admin user management API: lock, reset, audit logs

API reference for Alphabet admin endpoints: create users, list accounts, lock, unlock, force-logout, reset passwords, and view audit logs.

These endpoints allow administrators to manage user accounts across the Alphabet platform. Every endpoint under /api/v1/admin requires an authenticated session with the AdminOnly authorization policy. Requests without a valid bearer token or without the required role will be rejected.

All endpoints on this page require Authorization: Bearer <accessToken> with a token belonging to a user in the AdminOnly policy. Calls from non-admin accounts will be rejected.

Base path: /api/v1/admin/users

---

POST /api/v1/admin/users

Creates a new user account directly from the administration area, bypassing self-registration. This is useful for provisioning back-office, support, or managed accounts.

Authorization: Bearer <accessToken> — AdminOnly

Request body

email · string · required

The email address for the new account. Must be unique.

password · string · required

The initial password. Must meet the configured complexity requirements.

firstName · string · required

The user’s first name.

lastName · string · required

The user’s last name.

role · string · required

The role to assign to the new account (e.g., "Support", "Admin"). Accepted values depend on your role configuration.

Responses

201 Created — UserDto

userId · string

The unique identifier (GUID) for the created user.

email · string

The registered email address.

firstName · string

The user’s first name.

lastName · string

The user’s last name.

400 Bad Request — ProblemDetails — Creation failed (e.g., email already in use, password too weak, invalid role).

Example

curl -X POST https://localhost:5001/api/v1/admin/users \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "password": "TempPassword123!",
    "firstName": "Amina",
    "lastName": "Rahman",
    "role": "Support"
  }'

---

GET /api/v1/admin/users

Returns the full list of user accounts visible to administrators.

Authorization: Bearer <accessToken> — AdminOnly

No request body.

Responses

200 OK — UserDto[]

An array of user objects. Each item contains userId, email, firstName, and lastName.

---

GET /api/v1/admin/users/

Returns detailed information for a single user account, including account status, lockout state, two-factor configuration, and audit-friendly timestamps.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user to retrieve.

Responses

200 OK — AdminUserDetailDto

userId · string

The user’s unique identifier.

email · string

The registered email address.

firstName · string

The user’s first name.

lastName · string

The user’s last name.

roles · string[]

The list of roles assigned to the user.

isLockedOut · boolean

Whether the account is currently locked.

lockoutEnd · string

ISO 8601 timestamp of when the lockout expires, or null if the account is not locked or locked indefinitely.

twoFactorEnabled · boolean

Whether MFA is active on the account.

emailConfirmed · boolean

Whether the user’s email address has been verified.

createdAt · string

ISO 8601 timestamp of when the account was created.

400 Bad Request — ProblemDetails — User not found.

---

POST /api/v1/admin/users//lock

Locks the specified user account for a fixed duration or indefinitely. A locked account cannot sign in until it is unlocked.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user to lock.

Request body

durationMinutes · integer · required

How long to lock the account, in minutes. Pass 0 to lock indefinitely.

Responses

200 OK — Account locked.

400 Bad Request — ProblemDetails — Lock failed.

Example

# Lock a user indefinitely
curl -X POST https://localhost:5001/api/v1/admin/users/3fa85f64-5717-4562-b3fc-2c963f66afa6/lock \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "durationMinutes": 0
  }'

---

POST /api/v1/admin/users//unlock

Clears the lockout state for a previously locked account, allowing the user to sign in again.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user to unlock.

No request body.

Responses

200 OK — Account unlocked.

400 Bad Request — ProblemDetails — Unlock failed.

---

POST /api/v1/admin/users//reset-password

Resets the user’s password immediately without requiring the current password. This endpoint is intended for administrator-led account recovery and support scenarios.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user whose password should be reset.

Request body

newPassword · string · required

The new password. Must meet the configured complexity requirements.

Responses

200 OK — Password reset successfully.

400 Bad Request — ProblemDetails — Reset failed (e.g., password does not meet complexity requirements).

This endpoint does not require the user’s current password. It generates an internal reset token and applies the new password immediately. Consider notifying the user after performing an admin-initiated reset.

---

POST /api/v1/admin/users//send-reset-link

Creates a password reset token and emails a reset link to the user’s registered address using the configured communication provider.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user to send the reset link to.

No request body.

Responses

200 OK — Reset link sent.

400 Bad Request — ProblemDetails — Send failed (e.g., user not found or email delivery error).

---

POST /api/v1/admin/users//force-logout

Revokes all refresh tokens and updates the user’s security stamp, immediately invalidating all active sessions across every device and client.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user to force out.

No request body.

Responses

200 OK — All sessions revoked.

400 Bad Request — ProblemDetails — Force logout failed.

Existing access tokens remain technically valid until they expire naturally (15 minutes by default). Only refresh tokens are revoked immediately. To prevent re-authentication, combine this endpoint with an account lock if needed.

---

GET /api/v1/admin/users//audit-logs

Returns security and administrative activity for the selected user, including sign-in attempts, password actions, and account-management operations.

Authorization: Bearer <accessToken> — AdminOnly

Path parameters

userId · string · required

The GUID of the user whose audit logs to retrieve.

Query parameters

take · integer · default: "50"

The maximum number of records to return.

skip · integer · default: "0"

The number of records to skip before returning results. Use with take for pagination.

Responses

200 OK — AuditLogDto[]

An array of audit log entries for the user. Each entry records the event type, timestamp, and relevant details for the action.