API reference / Admin: team, roles, system
Admin: team, roles, system scope: admin — dashboard sessions only; API keys are refused here
Team members, role policies, effective configuration, and the audit log — dashboard sessions only.
Access is policy-based: a role is a set of permissions (read / publish / consume / manage / admin), and each team member acts with exactly what their role grants.
GET/v1/admin/teamMembers with role, invite status, and Cognito account state
Response · 200
{ "default_role": "member", "admin_group": "ADMIN", "cognito_directory": true,
"roles": [ { "name": "viewer", "description": "…", "permissions": ["read"],
"builtin": true, "members": 1 } ],
"members": [ { "email": "alice@example.com", "role": "viewer",
"status": "active", "invited_by": "dinesh@…",
"invited_at": "…", "joined_at": "…", "account": "CONFIRMED" } ] }POST/v1/admin/teamInvite a teammate
Request body
{ "email": "alice@example.com", "role": "member" }| The invite is keyed by email; the role applies when this address signs in or registers | |
| role | Any role name from /v1/admin/roles |
Response · 200
{ "email": "alice@example.com", "role": "member", "status": "invited",
"note": "Cognito emailed them a temporary password" }Errors
| 400 | invalid email or unknown role |
| 409 | {email} is already a team member |
PATCH/v1/admin/team/{email}Change a member's role — applies within ~30s, no re-sign-in
Request body
{ "role": "admin" }Response · 200
{ "email": "alice@example.com", "role": "admin",
"note": "takes effect within ~30 seconds" }Errors
| 400 | unknown role, or changing your own role |
| 404 | {email} is not a team member |
DELETE/v1/admin/team/{email}Remove a member (they fall back to the default role)
Response · 200
{ "email": "alice@example.com",
"note": "membership removed; if they can still sign in they fall back to the default role" }Errors
| 400 | you cannot remove yourself from the team |
| 404 | {email} is not a team member |
GET/v1/admin/rolesRole policies with member counts
Response · 200
{ "permissions": ["read", "publish", "consume", "manage", "admin"],
"roles": [ { "name": "publisher", "description": "Read and publish only",
"permissions": ["read", "publish"], "builtin": false, "members": 2 } ] }POST/v1/admin/rolesCreate a custom policy
Request body
{ "name": "publisher", "description": "Read and publish only",
"permissions": ["read", "publish"] }| name | 1–32 chars of a-z, 0-9, dashes. "none" is reserved (it means no access) |
| permissions | Non-empty subset of read, publish, consume, manage, admin (admin implies all) |
Response · 200
{ "name": "publisher", "permissions": ["read", "publish"] }Errors
| 400 | invalid name or permissions |
| 409 | role {name} already exists |
PATCH/v1/admin/roles/{role}Edit a custom role (built-ins are fixed)
Request body
{ "permissions": ["read", "publish", "consume"], "description": "…" }Response · 200
{ "name": "publisher", "permissions": ["read", "publish", "consume"],
"note": "takes effect within ~30 seconds" }Errors
| 400 | built-in role, or invalid permissions |
| 404 | no role named {role} |
DELETE/v1/admin/roles/{role}Delete an unused custom role
Response · 200
{ "name": "publisher", "deleted": true }Errors
| 400 | built-in role, or the current default role |
| 404 | no role named {role} |
| 409 | N member(s) still have this role; reassign them first |
GET/v1/admin/systemEffective configuration, storage sizes, runtime info
Response · 200
{ "auth": { "mode": "cognito", "cognito_pool": "…", "admin_group": "…",
"machine_tokens_configured": 0 },
"config": { "scheduler_enabled": true, "default_retention_ms": 604800000, … },
"storage": { "mongo_host": "mongo:27017", "data_bytes": 1048576,
"collections": { "messages": 1204, "deliveries": 940, … } },
"runtime": { "node": "v22.x", "uptime_s": 86400 } }GET/v1/admin/auditEvery administrative action with its actor
Query parameters
| limit | Max rows (default 200, cap 500) |
Response · 200
{ "events": [ { "ts": "…", "type": "team_invited",
"actor": "dinesh@…", "sub": null, "message_id": null,
"details": { "email": "alice@example.com", "role": "member" } } ] }