Suspend user

POST https://app.speybooks.com/api/v1/admin/users/{id}/suspend

Suspend or permanently ban a user account.

Flow

  1. Prevent self-suspension (returns 400)
  2. Prevent suspending admin users (returns 400)
  3. Set is_active = false, record suspended_at, suspended_reason, suspended_permanent
  4. Delete all active sessions (immediate logout)
  5. Write USER_SUSPENDED or USER_BANNED audit log

Request Body

  • reason — minimum 5 characters, required
  • permanent — boolean (default false). True = ban, false = suspension (can be reversed)

State Changes

FieldBeforeAfter
is_activetruefalse
suspended_atnullNOW()
suspended_reasonnullprovided reason
suspended_permanentfalseas provided
sessionsactivedeleted

Error responses:

  • 400 { code: "SELF_SUSPEND" } — cannot suspend yourself
  • 400 { code: "CANNOT_SUSPEND_ADMIN" } — admin users protected
  • 404 { code: "NOT_FOUND" } — user not found

Path parameters

id string required
User ID.

Body parameters

reason string required
Suspension reason (audit trail). Min 5 characters.
min length: 5
permanent boolean optional
True for permanent ban, false for temporary suspension. Default false.

Response

200 User suspended (or banned if permanent). All sessions invalidated.
Show response fields
message string

Error codes

400 Cannot suspend yourself or admin users.
404 User not found.