Admin API — Cognito User, Group & Module Management

The Admin API provides full lifecycle management for users in the shared Cognito user pool: creating and deleting accounts, assigning Cognito groups, controlling per-user data module access, and assigning tenant instance access. All endpoints are gated behind two independent checks.

Primary instance only. Every endpoint in this section returns 404 Not Found when called against a tenant instance (where expected_tenant != "*"). This is intentional — the admin plane is deliberately invisible on tenant deployments to prevent a tenant admin from managing shared-pool users. See dev-log/037.

Admin group required. The caller’s JWT must include the admin Cognito group. Any other authenticated user receives 403 Forbidden.

Authentication

Authorization: Bearer <id_token>

The token must be issued by the shared Cognito user pool. Tenant-specific pool tokens are rejected.

User Management

GET /api/admin/users

List all users in the Cognito user pool. Supports pagination and server-side filtering.

Query Parameters

limit

integer

default:"60"

Maximum number of users to return per page (Cognito maximum is 60).

pagination_token

string

Opaque token returned in a previous response to fetch the next page.

filter

string

Cognito filter expression, e.g. email = "user@example.com".

Response — `AdminUserListResponse`

users

array

required

Array of user summary objects.

Show AdminUserSummary fields

username

string

required

Cognito username (typically the email).

string

required

User’s email address.

sub

string

Cognito subject UUID — the stable unique identifier.

name

string

Display name.

empresa

string

Company / organisation name.

tenant

string

Tenant identifier assigned to this user.

data_scope

string

Comma-separated centro de beneficio codes restricting row-level access. Empty string means no restriction.

instances

array

List of additional instance slugs the user can access (custom:tenants).

status

string

Account status: CONFIRMED, FORCE_CHANGE_PASSWORD, UNCONFIRMED, etc.

enabled

boolean

Whether the account is currently enabled.

created

string

ISO-8601 creation timestamp.

modified

string

ISO-8601 last-modified timestamp.

pagination_token

string

Present when more users exist beyond this page. Pass as the pagination_token query parameter in the next request.

count

integer

required

Number of users in this response page.

curl -X GET "https://api.example.com/api/admin/users?limit=20" \
  -H "Authorization: Bearer <id_token>"

POST /api/admin/users

Create a new Cognito user. Returns the full AdminUserDetail on success with HTTP 201 Created.

Rate limited to 10 requests per minute. The temporary password must be shared with the user through a secure out-of-band channel.

Request Body — `CreateUserRequest`

string

required

The user’s email address. Must be a valid email format. Also used as the Cognito username. Returns 409 Conflict if the email is already registered.

temporary_password

string

required

Initial password (8–128 characters). The user will be forced to change it on first login. Returns 400 if it doesn’t meet Cognito’s password policy.

name

string

Display name for the user.

empresa

string

Company or organisation name stored as custom:company.

tenant

string

Tenant identifier stored as custom:tenantId.

Response — `AdminUserDetail`

Extends AdminUserSummary with usage statistics:

groups

array

List of Cognito group names the user belongs to.

session_count

integer

Total conversation sessions in DynamoDB.

total_messages

integer

Total messages sent across all sessions.

total_queries

integer

Total SQL queries executed.

last_active

string

ISO-8601 timestamp of the most recent session activity.

curl -X POST https://api.example.com/api/admin/users \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carlos.lopez@empresa.com",
    "temporary_password": "TempPass123!",
    "name": "Carlos López",
    "empresa": "Empresa S.A.",
    "tenant": "empresa-sa"
  }'

GET /api/admin/users/{username}

Retrieve full details for a single user, including Cognito groups and aggregated DynamoDB usage statistics.

Path Parameters

username

string

required

The Cognito username (typically the user’s email address).

Response

Returns AdminUserDetail (same shape as POST /api/admin/users response above).

curl -X GET https://api.example.com/api/admin/users/ana.garcia@empresa.com \
  -H "Authorization: Bearer <id_token>"

PUT /api/admin/users/{username}

Update one or more Cognito attributes for an existing user. Omitted fields are left unchanged.

Path Parameters

username

string

required

The Cognito username to update.

Request Body — `UpdateUserRequest`

name

string

New display name (name attribute).

empresa

string

Updated company name (custom:company).

tenant

string

Updated tenant identifier (custom:tenantId). The user must re-authenticate for the change to take effect.

data_scope

string

Row-level filter: comma-separated centro de beneficio codes, e.g. "1000,2000". Pass an empty string "" to remove all restrictions.

Response — `AdminActionResponse`

success

boolean

required

true on success.

message

string

required

Human-readable confirmation message.

curl -X PUT https://api.example.com/api/admin/users/ana.garcia@empresa.com \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ana García Ruiz", "data_scope": "1000,2000"}'

DELETE /api/admin/users/{username}

Permanently delete a Cognito user. This action cannot be undone. All Cognito records are removed; DynamoDB conversation history is not deleted by this endpoint.

Rate limited to 5 requests per minute. All admin delete actions are written to the audit log.

Path Parameters

username

string

required

The Cognito username to delete.

curl -X DELETE https://api.example.com/api/admin/users/carlos.lopez@empresa.com \
  -H "Authorization: Bearer <id_token>"

POST /api/admin/users/{username}/reset-password

Trigger a Cognito-initiated password reset. Cognito sends a reset code to the user’s email. Rate limited to 5 requests per minute.

curl -X POST https://api.example.com/api/admin/users/ana.garcia@empresa.com/reset-password \
  -H "Authorization: Bearer <id_token>"

POST /api/admin/users/{username}/disable

Disable a user account without deleting it. The user cannot log in while disabled but all records are preserved. Rate limited to 10 requests per minute.

curl -X POST https://api.example.com/api/admin/users/ana.garcia@empresa.com/disable \
  -H "Authorization: Bearer <id_token>"

POST /api/admin/users/{username}/enable

Re-enable a previously disabled user account. Rate limited to 10 requests per minute.

curl -X POST https://api.example.com/api/admin/users/ana.garcia@empresa.com/enable \
  -H "Authorization: Bearer <id_token>"

Group & Role Management

GET /api/admin/groups

List all Cognito groups in the shared user pool. Groups map to RBAC roles.

Response — `GroupListResponse`

groups

array

required

Show GroupInfo fields

group_name

string

required

Cognito group name (e.g. finance_lead, analyst).

description

string

Human-readable description of the group’s purpose.

created

string

ISO-8601 creation timestamp.

curl -X GET https://api.example.com/api/admin/groups \
  -H "Authorization: Bearer <id_token>"

POST /api/admin/users/{username}/groups

Add a user to a Cognito group. The new role permissions take effect on the user’s next token issuance.

Path Parameters

username

string

required

Cognito username.

Request Body — `UserGroupRequest`

group_name

string

required

Name of the Cognito group to add the user to.

curl -X POST https://api.example.com/api/admin/users/ana.garcia@empresa.com/groups \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{"group_name": "finance_lead"}'

DELETE /api/admin/users/{username}/groups/{group_name}

Remove a user from a Cognito group.

Path Parameters

username

string

required

Cognito username.

group_name

string

required

Name of the Cognito group to remove the user from.

curl -X DELETE \
  https://api.example.com/api/admin/users/ana.garcia@empresa.com/groups/finance_lead \
  -H "Authorization: Bearer <id_token>"

Module Assignment

Module overrides let administrators grant or revoke individual data modules beyond what a user’s base role provides. Overrides are persisted to DynamoDB and applied on every request without requiring a token refresh.

Both module endpoints require the admin.rbac.assign permission in addition to the admin Cognito group membership. Callers without this permission receive 403 Forbidden.

GET /api/admin/users/{user_id}/modules

Return the effective module set for a user: their role’s base modules, plus any DynamoDB overrides (additions and removals).

Path Parameters

user_id

string

required

The Cognito sub (UUID) or username of the target user.

Response — `UserModulesResponse`

user_id

string

required

Cognito subject UUID of the target user.

tenant

string

required

Tenant the user belongs to.

role

string

required

Effective role name (e.g. analyst).

base_modules

array

required

Modules granted by the user’s role before overrides.

modules_added

array

required

Modules explicitly granted via DynamoDB override.

modules_removed

array

required

Modules explicitly revoked via DynamoDB override.

effective_modules

array

required

Final computed module set: (base ∪ added) − removed.

curl -X GET \
  "https://api.example.com/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/modules" \
  -H "Authorization: Bearer <id_token>"

PUT /api/admin/users/{user_id}/modules

Set per-user module overrides. Completely replaces any previous override for the user. Pass empty arrays to clear all overrides.

Valid module slugs: ingresos, costos, nomina, presupuestos, pagos, produccion, compras, inventario, logistica. An unknown slug returns 400 Bad Request with a list of valid values.

Path Parameters

user_id

string

required

Cognito sub UUID or username of the target user.

Request Body — `SetUserModulesRequest`

modules_added

array

Module slugs to grant beyond the role’s default set. Defaults to [].

modules_removed

array

Module slugs to revoke from the role’s default set. Defaults to [].

curl -X PUT \
  "https://api.example.com/api/admin/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/modules" \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "modules_added": ["pagos"],
    "modules_removed": ["presupuestos"]
  }'

Instance Access

PUT /api/admin/users/{username}/instances

Assign the set of tenant instances a user is allowed to access, writing to the custom:tenants Cognito attribute. The user must sign out and back in for the change to take effect — access is read from the JWT.

Instance slugs are validated against the registered tenant registry. Unrecognised slugs return 400 Bad Request. Requires admin.rbac.assign permission.

Path Parameters

username

string

required

Cognito username of the target user.

Request Body — `SetUserInstancesRequest`

instances

array

required

List of registered instance slugs to assign. Pass an empty array to revoke all cross-instance access.

curl -X PUT \
  https://api.example.com/api/admin/users/ana.garcia@empresa.com/instances \
  -H "Authorization: Bearer <id_token>" \
  -H "Content-Type: application/json" \
  -d '{"instances": ["empresa-sa", "holding-mx"]}'

Cost Tracking

GET /api/admin/costs

Return a summary of LLM token costs aggregated globally, by user, and by agent node. Useful for monitoring spend and identifying heavy users.

Cost data is aggregated from the backend cost tracking store. The exact shape of global, by_user, and by_node sub-objects depends on the cost tracking configuration.

curl -X GET https://api.example.com/api/admin/costs \
  -H "Authorization: Bearer <id_token>"

Error Reference

Status	Condition
`400 Bad Request`	Invalid request body, unknown module/group name, or no update attributes provided.
`403 Forbidden`	Caller is authenticated but not in the `admin` Cognito group, or lacks `admin.rbac.assign`.
`404 Not Found`	Called on a non-primary tenant instance, or the target user/group was not found.
`409 Conflict`	A user with the given email already exists in Cognito.
`429 Too Many Requests`	Per-endpoint rate limit exceeded.
`502 Bad Gateway`	Unexpected error from Cognito or DynamoDB.

Chat & WebSocket

Schema Exploration

Admin & Identity

Documentation Index

​Authentication

​User Management

​GET /api/admin/users

​Query Parameters

​Response — AdminUserListResponse

​POST /api/admin/users

​Request Body — CreateUserRequest

​Response — AdminUserDetail

​GET /api/admin/users/{username}

​Path Parameters

​Response

​PUT /api/admin/users/{username}

​Path Parameters

​Request Body — UpdateUserRequest

​Response — AdminActionResponse

​DELETE /api/admin/users/{username}

​Path Parameters

​POST /api/admin/users/{username}/reset-password

​POST /api/admin/users/{username}/disable

​POST /api/admin/users/{username}/enable

​Group & Role Management

​GET /api/admin/groups

​Response — GroupListResponse

​POST /api/admin/users/{username}/groups

​Path Parameters

​Request Body — UserGroupRequest

​DELETE /api/admin/users/{username}/groups/{group_name}

​Path Parameters

​Module Assignment

​GET /api/admin/users/{user_id}/modules

​Path Parameters

​Response — UserModulesResponse

​PUT /api/admin/users/{user_id}/modules

​Path Parameters

​Request Body — SetUserModulesRequest

​Instance Access

​PUT /api/admin/users/{username}/instances

​Path Parameters

​Request Body — SetUserInstancesRequest

​Cost Tracking

​GET /api/admin/costs

​Error Reference

Build docs developers (and LLMs) love

Authentication

User Management

GET /api/admin/users

Query Parameters

Response — `AdminUserListResponse`

POST /api/admin/users

Request Body — `CreateUserRequest`

Response — `AdminUserDetail`

GET /api/admin/users/{username}

Path Parameters

Response

PUT /api/admin/users/{username}

Path Parameters

Request Body — `UpdateUserRequest`

Response — `AdminActionResponse`

DELETE /api/admin/users/{username}

Path Parameters

POST /api/admin/users/{username}/reset-password

POST /api/admin/users/{username}/disable

POST /api/admin/users/{username}/enable

Group & Role Management

GET /api/admin/groups

Response — `GroupListResponse`

POST /api/admin/users/{username}/groups

Path Parameters

Request Body — `UserGroupRequest`

DELETE /api/admin/users/{username}/groups/{group_name}

Path Parameters

Module Assignment

GET /api/admin/users/{user_id}/modules

Path Parameters

Response — `UserModulesResponse`

PUT /api/admin/users/{user_id}/modules

Path Parameters

Request Body — `SetUserModulesRequest`

Instance Access

PUT /api/admin/users/{username}/instances

Path Parameters

Request Body — `SetUserInstancesRequest`

Cost Tracking

GET /api/admin/costs

Error Reference