Safety Net Blueprint — User Service API

▶ GET /users List users #

List users with filtering by role, county, or status. Requires users:read permission.

Parameters

Name Type In Req Description

▶q string query Search query using field:value syntax. Multiple conditions separated by

Search query using field:value syntax. Multiple conditions separated by spaces are ANDed together.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples in this documentation show human-readable syntax for clarity.

Syntax

Pattern	Description	Example
`term`	Full-text exact match	`john`
`term`	Full-text contains	`john`
`term*`	Full-text starts with	`john*`
`*term`	Full-text ends with	`*smith`
`field:value`	Exact match on field	`status:approved`
`field:value`	Contains (case-insensitive)	`name:john`
`field:value*`	Starts with	`name:john*`
`field:*value`	Ends with	`email:*@example.com`
`field:"value"`	Quoted value (for spaces)	`name:"john doe"`
`field.nested:value`	Nested field (dot notation)	`address.state:CA`
`field:>value`	Greater than	`income:>1000`
`field:>=value`	Greater than or equal	`income:>=1000`
`field:<value`	Less than	`income:<5000`
`field:<=value`	Less than or equal	`income:<=5000`
`field:val1,val2`	Match any value (OR)	`status:approved,pending`
`-field:value`	Exclude / negate	`-status:denied`
`field:*`	Field exists (not null)	`email:*`
`-field:*`	Field does not exist	`-deletedAt:*`

Examples

john — exact match for "john" in searchable fields
john — contains "john" in searchable fields
name:smith — name contains "smith" (case-insensitive)
email:*@example.com — email ends with "@example.com"
status:approved — exact match on status field
status:approved,pending — status is "approved" OR "pending"
income:>=1000 — income greater than or equal to 1000
created:>2024-01-01 — created after January 1, 2024
status:approved income:>=1000 — approved AND income >= 1000 (multiple conditions)
-status:denied — exclude records with status "denied"
-deletedAt:* — only records where deletedAt does not exist
applicant.state:CA — nested field filter

URL Encoding Reference

When manually constructing URLs, encode these characters:

Character	Encoded
(space)	`%20` or `+`
`"`	`%22`
`:`	`%3A`
`>`	`%3E`
`<`	`%3C`
`,`	`%2C`

Example: `` Human-readable: q=status:approved income:>=1000 URL-encoded: q=status%3Aapproved%20income%3A%3E%3D1000 ``

limit

integer

query

Maximum number of items to return (1-100).

offset

integer

query

Number of items to skip before collecting results.

▶sort string query Comma-separated list of fields to sort the response by. Prefix a field

Comma-separated list of fields to sort the response by. Prefix a field with - for descending order. The first field is the primary sort; subsequent fields are tie-breakers in declaration order.

URL Encoding: This parameter must be URL-encoded when sent over HTTP. Most HTTP clients handle this automatically. Examples below show human-readable syntax for clarity.

Which fields a given list endpoint allows is declared in the operation's x-sortable.fields extension. Sending a field name not present in that list returns 400 FIELD_NOT_SORTABLE. Sending a field name that doesn't exist on the resource schema returns 400 INVALID_SORT_FIELD. When this parameter is omitted, the operation's x-sortable.default (if declared) is applied; otherwise no client-driven sort is applied. A configured tie-breaker (default id) is always appended for stable pagination.

See api-patterns.yaml#sorting for the full convention and docs/architecture/x-extensions.md for the extension shape.

Syntax

Pattern	Description	Example
`fieldName`	Ascending	`sort=createdAt`
`-fieldName`	Descending	`sort=-createdAt`
`field1,field2`	Multi-field	`sort=status,-priority`
`nested.field`	Nested field via dot notation	`sort=name.lastName`

Examples

sort=createdAt — oldest first
sort=-createdAt — newest first
sort=-priority,dueDate — highest priority first, then oldest due date
sort=name.lastName,name.firstName — alphabetical by surname, then given name

Responses

200 Paginated list of users.

▶ UserList

total integer required Total number of items available.

limit integer required Maximum number of items requested.

offset integer required Number of items skipped before the current page.

hasNext boolean Whether more items are available beyond the current page.

▶ items array[User] required

idpSubject string Subject identifier from the Identity Provider. Immutable after creation. Format varies by IdP (e.g., "auth0|507f1f77bcf86cd799439011").

email string (email) User's email address (from IdP or manually set).

name string

▶ roles Role Role and permissions for authorization.

name string required Authorization roles that determine base permissions and data scoping. Used in state machine actors arrays and JWT role claims. - applicant: Self-service access to own applications (scoped by personId) - case_worker: Process applications for assigned county - supervisor: Oversee case workers, approve determinations (may span counties) - county_admin: Administer county staff and configuration - state_admin: Statewide oversight and administration (all counties) - partner_readonly: External partner with limited read access - system: Automated service account for background and inter-service operations

enumapplicant case_worker supervisor county_admin state_admin partner_readonly system

permissions array[string] Permission strings in the format {resource}:{action}. Examples: applications:read, persons:update, users:create

status string User account status.

enumactive inactive pending suspended

counties array[string] County FIPS codes assigned to the user.

organizationId string (uuid)

personId string (uuid) Link to Person record (for applicants).

caseWorkerId string (uuid) Link to CaseWorker record (for staff).

preferences object User preferences for the application. Structure is flexible — states define their own fields via overlays. Example fields: timezone, dateFormat, itemsPerPage, language, theme, etc.

userId string (uuid) required User Service identifier. Same value as User.id on the REST resource.

▶ roles Role required Role and permissions for authorization.

name string required Authorization roles that determine base permissions and data scoping. Used in state machine actors arrays and JWT role claims. - applicant: Self-service access to own applications (scoped by personId) - case_worker: Process applications for assigned county - supervisor: Oversee case workers, approve determinations (may span counties) - county_admin: Administer county staff and configuration - state_admin: Statewide oversight and administration (all counties) - partner_readonly: External partner with limited read access - system: Automated service account for background and inter-service operations

enumapplicant case_worker supervisor county_admin state_admin partner_readonly system

permissions array[string] Permission strings in the format {resource}:{action}. Examples: applications:read, persons:update, users:create

ui object read-only Computed UI permissions and display data for frontend feature toggling. Backend computes these from role and permissions to provide a UI-friendly interface for showing/hiding features. Structure is flexible — states define their own fields via overlays. Example fields: name, availableModules, canApproveApplications, etc.

preferences object User preferences for the application. Structure is flexible — states define their own fields via overlays. Example fields: timezone, dateFormat, itemsPerPage, language, theme, etc.

id string (uuid) required read-only Unique identifier for the user.

userId string (uuid) read-only Alias for id, used in JWT claims context (BackendAuthContext.userId). Same value as id.

createdAt string (date-time) required read-only Timestamp when the user was created.

updatedAt string (date-time) required read-only Timestamp when the user was last updated.

400 The request is malformed or contains invalid parameters.

▶ BadRequest

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

401 Authentication is required or the provided credentials are invalid.

▶ Unauthorized

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

403 The authenticated user does not have permission to perform this action.

▶ Forbidden

code string required Machine-readable error code.

message string required Human-readable error description.

details array[object] Additional error details.

▶ POST /users Create a user #

Create a new user record. The user must already exist in the IdP. Links the IdP identity (sub) to roles and county assignments. Requires users:create permission.

Request body required

▶ UserCreate

idpSubject string Subject identifier from the Identity Provider. Immutable after creation. Format varies by IdP (e.g., "auth0|507f1f77bcf86cd799439011").

email string (email) User's email address (from IdP or manually set).

name string

▶ roles Role Role and permissions for authorization.

name string required Authorization roles that determine base permissions and data scoping. Used in state machine actors arrays and JWT role claims. - applicant: Self-service access to own applications (scoped by personId) - case_worker: Process applications for assigned county - supervisor: Oversee case workers, approve determinations (may span counties) - county_admin: Administer county staff and configuration - state_admin: Statewide oversight and administration (all counties) - partner_readonly: External partner with limited read access - system: Automated service account for background and inter-service operations

enumapplicant case_worker supervisor county_admin state_admin partner_readonly system

permissions array[string] Permission strings in the format {resource}:{action}. Examples: applications:read, persons:update, users:create

status string User account status.

enumactive inactive pending suspended

counties array[string] County FIPS codes assigned to the user.

organizationId string (uuid)

personId string (uuid) Link to Person record (for applicants).

caseWorkerId string (uuid) Link to CaseWorker record (for staff).

preferences object User preferences for the application. Structure is flexible — states define their own fields via overlays. Example fields: timezone, dateFormat, itemsPerPage, language, theme, etc.

Responses

201 User created successfully.

▶ User