Users API

Programmatically manage user accounts within your organization — create users, update profiles, control access, and assign roles.

Authentication: session token only (Authorization: Bearer <session_token>). User, role, and organization-management endpoints do not accept API keys.

Naming convention

The /auth/* endpoints (registration, login, API keys) use camelCase in their bodies (displayName, userId). The /v1/users/* endpoints below use snake_case (display_name, user_id). Both apply to the same User entity — see Authentication for the auth-side endpoints.

---

Endpoints

Method	Path	Permission
GET	/v1/users	users:read
GET	/v1/users/{user_id}	users:read
POST	/v1/users	users:create
PATCH	/v1/users/{user_id}	users:update
DELETE	/v1/users/{user_id}	users:delete
POST	/v1/users/{user_id}/roles	users:update
DELETE	/v1/users/{user_id}/roles/{role_id}	users:update

---

GET /v1/users

List users in your organization with offset pagination.

Query	Type	Default	Description
status	string	—	active, suspended, or deleted
limit	integer	50	Page size (max 100)
offset	integer	0	Skip the first N records

{
  "users": [
    {
      "user_id": "usr_01JF8RUS1A2B3C4D5E6F7G8H9I",
      "email": "jane.doe@yourcompany.com",
      "display_name": "Jane Doe",
      "roles": ["admin", "developer"],
      "status": "active",
      "mfa_enabled": true,
      "email_verified": true,
      "sso_provider": "okta",
      "last_login_at": "2026-04-30T09:30:00Z",
      "created_at": "2026-01-15T12:00:00Z"
    }
  ],
  "pagination": { "total": 12, "limit": 50, "offset": 0 }
}

---

GET /v1/users/{user_id}

Returns a single user object with the same schema as the list rows above.

---

POST /v1/users

Create a user in your organization.

{
  "email": "new.user@yourcompany.com",
  "display_name": "New User",
  "password": "SecureP@ssword1",
  "roles": ["developer"]
}

Field	Type	Required	Description
email	string	Yes	Unique within the organization
display_name	string	Yes	Display name shown in the dashboard
password	string	No	Initial password. Omit to send a setup email instead
roles	string[]	No	Role IDs (role_*) or system role names (admin, auditor, developer, viewer)

Response — 201 Created:

{
  "user_id": "usr_01JF8RUS2B3C4D5E6F7G8H9I0J",
  "email": "new.user@yourcompany.com",
  "display_name": "New User",
  "roles": ["developer"],
  "status": "active",
  "email_verified": false,
  "created_at": "2026-05-01T14:22:00Z"
}

If password is omitted, the platform sends a verification + password-setup email; the user lands in active/email_verified: false until they complete the link.

---

PATCH /v1/users/{user_id}

Partial update.

Field	Type	Description
display_name	string	Updated display name
avatar_url	string	Avatar image URL
mfa_enabled	boolean	Enable / disable MFA for this user
status	string	active or suspended

Returns the updated user object.

---

DELETE /v1/users/{user_id}

Soft-delete: user data and governance logs are retained for compliance, but the user immediately loses access.

{ "message": "User deactivated successfully.", "user_id": "usr_01JF8RUS1A2B3C4D5E6F7G8H9I" }

---

Role assignment

Assign a role

POST /v1/users/{user_id}/roles

{ "role_id": "role_01JF8RRO1A2B3C4D5E6F7G8H9I" }

{
  "message": "Role assigned successfully.",
  "user_id": "usr_01JF8RUS1A2B3C4D5E6F7G8H9I",
  "role_id": "role_01JF8RRO1A2B3C4D5E6F7G8H9I",
  "role_name": "compliance-reviewer"
}

Remove a role

DELETE /v1/users/{user_id}/roles/{role_id}

{
  "message": "Role removed successfully.",
  "user_id": "usr_01JF8RUS1A2B3C4D5E6F7G8H9I",
  "role_id": "role_01JF8RRO1A2B3C4D5E6F7G8H9I"
}

---

Errors

HTTP	error.code	Cause
400	validation_error	Body or query failed schema validation
401	unauthenticated	Missing or invalid session token
403	forbidden	Caller lacks the required permission
404	not_found	User not found in your organization
409	conflict	A user with that email already exists

---

Next steps

• Define roles and permissions → Roles API
• Manage your organization profile → Organization API
• Invite a user via email link → Invitations API
• Authentication contract → Authentication