Users and roles

Operations

Operation	Scope	Description
GET /roles	read:roles	A paged list of the roles available in the tenant.
GET /users	read:users	A paged, filterable list of users.
GET /users/{username}	read:users	A single user.
POST /users	write:users	Create a user.
PATCH /users/{username}	write:users	Update a user.

Creating a user

POST /identity-management/acme/users
Content-Type: application/json

{
  "username": "dlopez",
  "password": "<initial password>",
  "email": "dana.lopez@example.com",
  "agentCode": "A1051",
  "roles": ["Agent"],
  "status": "Approved"
}

Field	Notes
username	Required. Must be unique in the tenant.
password	The initial password. Must meet the password policy.
email	Must not belong to another user.
agentCode	Links the user to an agent in the Agency Management API.
roles	Role names from GET /roles.
status	Pending or Approved. If left out, the tenant's default is used.

caution

Send passwords only over HTTPS, never log them, and let users choose their own password on first sign-in where you can.

Updating a user

PATCH /users/{username} accepts password, email, agentCode, roles and status, following the partial update rules. When you send roles, it replaces the user's whole set of roles.

Finding users

GET /users filters:

Parameter	Description
email	Filter by email.
agentCode	Filter by linked agent.
status	Pending or Approved.
role	Users with this role.
minCreatedAt, maxCreatedAt	A creation time range (UTC).
sort	field:direction. Fields: username, email, agentCode, createdAt.
pageIndex, pageSize	See Pagination.

User statuses

Status	Meaning
Pending	Created but waiting for approval. The user can't sign in yet.
Approved	Active and able to sign in.