Users

GET    /orgs/{orgId}/api/v1/admin/users
POST   /orgs/{orgId}/api/v1/admin/users
GET    /orgs/{orgId}/api/v1/admin/users/{userId}
PUT    /orgs/{orgId}/api/v1/admin/users/{userId}
PATCH  /orgs/{orgId}/api/v1/admin/users/{userId}
DELETE /orgs/{orgId}/api/v1/admin/users/{userId}
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/block
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/unblock
GET    /orgs/{orgId}/api/v1/admin/users/{userId}/roles
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/roles
DELETE /orgs/{orgId}/api/v1/admin/users/{userId}/roles/{roleId}
GET    /orgs/{orgId}/api/v1/admin/users/{userId}/groups
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/groups
DELETE /orgs/{orgId}/api/v1/admin/users/{userId}/groups/{groupId}
GET    /orgs/{orgId}/api/v1/admin/users/{userId}/permissions
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/permissions
DELETE /orgs/{orgId}/api/v1/admin/users/{userId}/permissions/{permissionId}
PUT    /orgs/{orgId}/api/v1/admin/users/{userId}/password
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/password-reset
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/verify-email
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/mark-verified
POST   /orgs/{orgId}/api/v1/admin/users/{userId}/mfa/reset

Authentication

All user management endpoints require a valid admin API key or a Bearer token issued to a user with settings.manage permission.

Method	Header
API Key	`Authorization: ApiKey lmk_...` or `X-API-Key: lmk_...`
Bearer Token	`Authorization: Bearer eyJ...`

The User Object

User Object
{
  "id": "01JF3KABCDE...",
  "email": "john@acme.com",
  "username": "john.doe",
  "name": "John Doe",
  "givenName": "John",
  "familyName": "Doe",
  "emailVerified": true,
  "isActive": true,
  "isBlocked": false,
  "mfaEnabled": false,
  "locale": "en",
  "zoneinfo": "America/New_York",
  "roles": ["admin"],
  "groups": ["engineering"],
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-03-01T08:00:00Z",
  "lastLoginAt": "2026-04-10T09:15:00Z"
}

List Users

List Users
curl "https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users?page=1&limit=50" \
  -H "Authorization: ApiKey lmk_abc123"

Query Parameters

Parameter	Description
`page`	Page number (default: 1)
`limit`	Results per page (default: 20, max: 100)
`search`	Filter by email, name, or username
`isActive`	Filter by active status (`true`/`false`)

List Response
{
  "data": {
    "data": [{ "id": "01JF3K...", "email": "john@acme.com" }],
    "meta": { "total": 142, "page": 1, "limit": 50, "totalPages": 3 }
  }
}

Create User

Create a User
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "name": "Jane Smith",
    "givenName": "Jane",
    "familyName": "Smith",
    "password": "Str0ng!Pass",
    "emailVerified": true,
    "roles": ["viewer"]
  }'

Returns 201 Created with the new user object.

note

Passwords must be at least 8 characters. Omit password to create a user who must set their password on first login.

Update User

Update a User (PUT)
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "givenName": "Jane",
    "familyName": "Doe"
  }'

Use PATCH for partial updates (only the supplied fields are changed).

Block / Unblock a User

Block a User
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../block \
  -H "Authorization: ApiKey lmk_abc123"

Unblock a User
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../unblock \
  -H "Authorization: ApiKey lmk_abc123"

Manage User Roles

Get User Roles

Get User Roles
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../roles \
  -H "Authorization: ApiKey lmk_abc123"

Assign a Role

Assign a Role to a User
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../roles \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "01JF3KROLE..."}'

Remove a Role

Remove a Role from a User
curl -X DELETE https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../roles/01JF3KROLE... \
  -H "Authorization: ApiKey lmk_abc123"

Manage User Groups

Get User Groups

Get User Groups
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../groups \
  -H "Authorization: ApiKey lmk_abc123"

Add to a Group

Add User to a Group
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../groups \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"groupId": "01JF3KGRP..."}'

Remove from a Group

Remove User from a Group
curl -X DELETE https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../groups/01JF3KGRP... \
  -H "Authorization: ApiKey lmk_abc123"

Manage User Permissions

Direct permissions on users are additive — the user retains all permissions inherited from their roles and groups.

Get User Permissions

Get User Permissions
curl https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../permissions \
  -H "Authorization: ApiKey lmk_abc123"

Assign a Permission

Assign a Permission to a User
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../permissions \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"permissionId": 42}'

Remove a Permission

Remove a Permission from a User
curl -X DELETE https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../permissions/42 \
  -H "Authorization: ApiKey lmk_abc123"

Password Management

Set Password (admin override)
curl -X PUT https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../password \
  -H "Authorization: ApiKey lmk_abc123" \
  -H "Content-Type: application/json" \
  -d '{"password": "NewStr0ng!Pass", "requireChange": true}'

Send Password Reset Email
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../password-reset \
  -H "Authorization: ApiKey lmk_abc123"

Email Verification

Send Verification Email
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../verify-email \
  -H "Authorization: ApiKey lmk_abc123"

Mark Email as Verified (without sending email)
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../mark-verified \
  -H "Authorization: ApiKey lmk_abc123"

Reset MFA

Reset MFA
curl -X POST https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE.../mfa/reset \
  -H "Authorization: ApiKey lmk_abc123"

Clears all registered MFA methods for the user. The user will be prompted to re-enroll on next login if MFA is required.

Delete User

Delete a User
curl -X DELETE https://app.lumoauth.dev/orgs/acme-corp/api/v1/admin/users/01JF3KABCDE... \
  -H "Authorization: ApiKey lmk_abc123"

Returns 204 No Content on success. This action is irreversible.

Authentication​

The User Object​

List Users​

Query Parameters​

Create User​

Update User​

Block / Unblock a User​

Manage User Roles​

Get User Roles​

Assign a Role​

Remove a Role​

Manage User Groups​

Get User Groups​

Add to a Group​

Remove from a Group​

Manage User Permissions​

Get User Permissions​

Assign a Permission​

Remove a Permission​

Password Management​

Email Verification​

Reset MFA​

Delete User​