LAYER 5 · HUMANS & TENANTS

Reference

Endpoints, the user record, session claims, and the role-capability matrix — everything on this page mirrors the code, not aspiration.

Auth & user endpoints

Endpoint	Min role	Body	Errors
`POST /orgs/register`	public	`org_name` (2–120), `email`, `password` (8–200), `name?` → 201 with `org_id`, one-time `api_key`, `user`, session `token`	`409` email already registered
`POST /auth/login`	public	`email`, `password` → `token` + `user`	`401` invalid credentials — identical for unknown email, wrong password, and disabled account
`GET /auth/me`	viewer	— → `via` (`session`/`api_key`), `org_id`, `role`, `user` (null for the API key)	`401` bad credential
`POST /auth/password`	viewer (session only)	`current_password`, `new_password` (8–200)	`400` if called with the API key · `403` current password is wrong
`GET /users`	admin	— → array of user records for your org	`403` requires the admin role
`POST /users`	admin	`email`, `password` (8–200), `role` (default `developer`), `name?`	`409` email already registered · `422` unknown role · `403` role error
`PATCH /users/{id}`	admin	`role?`, `status?` (`active`/`disabled`), `name?` — no password field	`404` unknown user (foreign or malformed IDs look identical) · `409` cannot remove the last admin · `422` bad role/status · `403` role error

Any authenticated caller below an endpoint's floor gets 403 requires the <role> role (you are <role>).

Field	Type	Notes
`id`	UUID	Primary key, generated
`org_id`	UUID	The tenant — foreign key to orgs
`email`	text	Globally unique across all tenants; the login identifier
`password_hash`	text	bcrypt; never returned by any endpoint
`name`	text	Display name, defaults to empty
`role`	text	One of `viewer` │ `developer` │ `security` │ `admin`; default `developer`
`status`	text	`active` │ `disabled`; checked fresh on every request
`created_at / updated_at`	timestamptz	ISO-8601 strings in API responses

Claim	Value
`sub`	The user's ID (UUID)
`org`	The tenant's org ID
`email`	The account email at issue time
`role`	Role at issue time — advisory only; the account row is re-checked per request
`typ`	`user` — what makes this token unusable as an agent identity
`iat / exp`	Issued-at and expiry; `exp = iat + 12 h`

Action	viewer	developer	security	admin
Read registry, calls, audit, exports, approvals list	✓	✓	✓	✓
Register / update agents, rotate agent tokens, activate	—	✓	✓	✓
Approve / suspend / reactivate / decommission agents, decide approvals, manage MCP servers, edit org policy	—	—	✓	✓
Create users, change roles, disable accounts	—	—	—	✓

The org API key holds the admin row of this matrix as a machine principal. For how this layer fits the other four, see The five layers.