6. Tenant Users and Roles

6.1 Tenant Users

Endpoint Summary

GET /api/v1/tenants/{tenant_id}/users

List tenant users

Return all users that belong to the specified tenant. The response includes a total count field. Tenant Admins can only list users within their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, UserListResponse)

Example

{
   "total" : 1,
   "users" : [
      {
         "auth_settings" : {
            "auth_mode" : "local"
         },
         "created_at" : "2026-01-01T00:00:00Z",
         "display_name" : "Alice Anderson",
         "email" : "alice@fintech.example.com",
         "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
         "updated_at" : "2026-01-01T00:00:00Z",
         "username" : "alice"
      }
   ]
}

POST /api/v1/tenants/{tenant_id}/users

Create tenant user

Create a new tenant user within the specified tenant. The name must be unique within the tenant. The password is hashed server-side; the plaintext value is never stored.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: UserCreateRequest

Request payload for creating a Tenant User.

The password is hashed server-side before storage; the plaintext value is never persisted. The name must be unique within the tenant.

Example

{
   "auth_settings" : {
      "auth_mode" : "local"
   },
   "display_name" : "Alice Anderson",
   "email" : "alice@fintech.example.com",
   "password" : "secure-password",
   "username" : "alice"
}

Responses

Response Body (201, UserCreateResponse)

Example

{
   "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

GET /api/v1/tenants/{tenant_id}/users/{user_id}

Get tenant user

Retrieve a specific tenant user by ID. Returns 404 if the user does not exist or belongs to a different tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, GetUserResponse)

Example

{
   "user" : {
      "auth_settings" : {
         "auth_mode" : "local"
      },
      "created_at" : "2026-01-01T00:00:00Z",
      "display_name" : "Alice Anderson",
      "email" : "alice@fintech.example.com",
      "id" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "updated_at" : "2026-01-01T00:00:00Z",
      "username" : "alice"
   }
}

PATCH /api/v1/tenants/{tenant_id}/users/{user_id}

Update tenant user

Apply a partial update to the specified tenant user: set a new password, change the authentication backend (auth_settings), update the email and/or the display_name. At least one field must be supplied. This is an administrative operation - the caller does not need to supply the current password. Returns 400 if a password change is requested for a user whose resulting auth mode is not local. Returns 404 if the user does not exist or belongs to a different tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: UserPatchRequest

Request payload for updating a Tenant User.

Allows partial updates of new_password, auth_settings, email and/or display_name; at least one must be supplied. Administrative operation - the caller does not need to supply the current password. Intended for Tenant Admin or Platform Admin use only.

Responses

DELETE /api/v1/tenants/{tenant_id}/users/{user_id}

Delete tenant user

Permanently delete a tenant user by ID, together with everything that would still authenticate as it: the API tokens it holds and its role bindings. Returns 404 if the user does not exist or belongs to a different tenant. Returns 409 for the Platform Admin, which cannot be deleted by any caller. Tenant Admins can only delete users within their own tenant.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

6.2 Tenant User Roles

Endpoint Summary

GET /api/v1/tenants/{tenant_id}/users/{user_id}/roles

List tenant user roles

Returns the RBAC roles assigned to a tenant user.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, RolesResponse)

PATCH /api/v1/tenants/{tenant_id}/users/{user_id}/roles

Set tenant user roles

Replaces the RBAC roles assigned to a tenant user. The roles of a protected user cannot be changed through the API, and the request is refused with 409.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Request Body (application/json, required)

Schema: SetRolesRequest

Request payload for replacing the full role set of a Tenant User.

Responses

Response Body (200, RolesResponse)