Identity API — Effective Role & Permission Detail

The Identity API exposes a single endpoint — GET /api/me — that returns everything the frontend needs to make conditional rendering decisions: the user’s effective role, every granted permission key, the list of data modules the agent may query on their behalf, labor-cost restrictions, and the set of tenant instances they can access.

Client-side gating based on this response is for UX only. Every action is independently enforced server-side. Never use GET /api/me as a security gate in client code.

Authentication

Authorization: Bearer <id_token>

A valid Cognito-issued JWT is required. The role and permissions are resolved from the user’s Cognito group membership at request time.

GET /api/me

Returns the calling user’s resolved Principal as a public dictionary. The same shape is embedded in every agent graph state object, so the agent nodes always operate with an up-to-date copy of the caller’s access.

Response — `MeResponse`

user_id

string

required

Cognito subject (sub) — the stable UUID that uniquely identifies the user across all systems. Use this as the canonical user key in DynamoDB records.

username

string

required

Display username. In most deployments this is the user’s email address.

string

required

User’s email address.

tenant

string

required

Tenant identifier assigned to this user (custom:tenantId). Determines which deployment instance the user’s data queries are routed to. Defaults to "default" if unset.

role

string

required

The user’s effective role name, resolved from their Cognito group membership.

Value	Description
`platform_admin`	Vendor staff — cross-tenant operations, full access to all instances.
`org_admin`	Organization administrator — manages users and roles within their tenant.
`finance_lead`	Finance lead analyst — full read access plus data export.
`analyst`	Standard analyst — chat queries, visualisations, SQL view.
`viewer`	Read-only — chat queries only, no SQL or export access.

permissions

array

required

Sorted list of atomic permission keys granted to this user. The full set of possible values is listed below.

Show All permission values

Key	Description
`chat.query`	Submit queries to the Text-to-SQL agent.
`viz.create`	Request chart and visualisation generation.
`feedback.submit`	Submit thumbs-up / thumbs-down feedback on answers.
`sql.view_raw`	View the generated SQL in agent responses.
`data.export`	Download query results as Excel or CSV.
`file.upload`	Upload Excel/CSV files for ad-hoc analysis.
`history.view_all`	View conversation history for all users (not just own).
`admin.users.read`	Read user list and user details in the admin panel.
`admin.users.write`	Create, update, disable, and delete users.
`admin.audit.read`	Read the admin audit log.
`admin.rbac.assign`	Change a user’s role or data module overrides.
`platform.manage`	Cross-tenant platform-level operations (vendor only).

modules

array

required

Sorted list of data module slugs the agent is allowed to query for this user. The effective set is computed as (role_base ∪ modules_added) − modules_removed from DynamoDB overrides.

Show All module values

Slug	Business domain
`ingresos`	Sales and invoicing (revenue).
`costos`	Cost centres, cost of sales, and profitability.
`nomina`	Payroll — add-on to `costos`; exposes Costos Mano de Obra accounts.
`presupuestos`	Budget vs. actuals.
`pagos`	Payment gateway transactions (BREB, Rappi, Redeban, etc.).
`produccion`	Manufacturing orders and unit production cost.
`compras`	Purchase orders, procurement history, and delivery plans.
`inventario`	Material documents and stock movements.
`logistica`	Transport documents and delivery stages.

labor_cost_restricted

boolean

required

true when the user has the costos module but not the nomina add-on. When true, the schema linker and SQL validator hide all Costos Mano de Obra account lines from generated queries and responses.

admin_panel

boolean

required

true only on the primary instance (where expected_tenant == "*"). The frontend uses this flag to show or hide the admin panel navigation link. The admin plane does not exist on tenant-specific deployments — see dev-log/037.

allowed_tenants

array

required

Additional instance slugs the user is authorised to access beyond their home tenant (custom:tenants). A platform_admin can access all instances regardless of this list.

Example

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

GET /api/admin/roles

Returns the full role catalog, including pre-designed inactive roles. Requires admin.users.read permission.

Response — `RoleCatalogResponse`

roles

array

required

List of role definitions, sorted by rank descending (highest authority first).

Show RoleInfo fields

name

string

required

Role slug (e.g. finance_lead).

description

string

required

Human-readable description of the role’s purpose.

rank

integer

required

Authority level. Higher values indicate more authority and are used to enforce management hierarchies.

active

boolean

required

true if this role is currently in use. Pre-designed roles ship as false.

permissions

array

required

Sorted list of permission keys granted by this role.

modules

array

required

Sorted list of data module slugs granted by this role.

all_permissions

array

required

Sorted list of every permission key defined in the system, regardless of role assignment.

all_modules

array

required

Sorted list of every module slug defined in the system.

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

Error Reference

Status	Condition
`401 Unauthorized`	Missing or expired JWT.
`403 Forbidden`	Valid JWT but insufficient permissions (e.g. calling `/api/admin/roles` without `admin.users.read`).
`429 Too Many Requests`	Rate limit exceeded.

Chat & WebSocket

Schema Exploration

Admin & Identity

Identity API — Effective Role & Permission Detail

Authentication

GET /api/me

Response — `MeResponse`

Example

GET /api/admin/roles

Response — `RoleCatalogResponse`

Error Reference

Build docs developers (and LLMs) love

Chat & WebSocket

Schema Exploration

Admin & Identity

Documentation Index

​Authentication

​GET /api/me

​Response — MeResponse

​Example

​GET /api/admin/roles

​Response — RoleCatalogResponse

​Error Reference

Build docs developers (and LLMs) love

Authentication

GET /api/me

Response — `MeResponse`

Example

GET /api/admin/roles

Response — `RoleCatalogResponse`

Error Reference