Clear failed_login_count + lockout_until for a user

POST

/admin/users/{ref}/unlock-account

• Local development behind nginx (port 8088 by default)

Manually clears the per-username lockout state a user has accumulated. Called by admins for legitimate users who got stuck (typo cascades, retrying a forgotten password).

Gated on auth.unlock (admin-only by seed). Idempotent: calling on an already-unlocked user returns 200 with unlocked=false; no audit fires for the no-op case.

Audit emits auth.lockout.cleared with subject = target user_ref, actor = admin.user_ref, metadata.source=“admin”

• metadata.prior_failed_count.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

Responses

200

Unlock attempted (see body for effect).

Returned by POST /admin/users/{ref}/unlock-account. Reports whether the call actually unlocked (unlocked=true) or found the user already-unlocked (unlocked=false — idempotent no-op).

object

user_ref

required

integer format: int64

unlocked

required

True when the call cleared existing lockout state (audit fired); false when the user was already unlocked (no state change; no audit).

boolean

prior_failed_count

required

The failed_login_count value BEFORE the unlock cleared it. Zero when unlocked=false.

integer format: int32

401

Authentication required, missing, or invalid

object

error

required

Human-readable error summary

string

Example

the request could not be completed

Example

{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed