Admin

The admin surface is split by scope: org admins manage their own organization's users, workspaces, and members; superadmins additionally manage cross-org platform state — organizations themselves, provider settings, secrets, the model registry, SSO, and bot integrations. Every route below is declarative at the boundary (a FastAPI dependency, not an inline if role == ... check), and superadmin-composable custom roles can grant or withhold each permission individually — the "Auth" line below is the default/typical gate, not a hardcoded ceiling.

Organizations (superadmin)

List organizations

List all organizations on the platform.

GET /api/v1/admin/orgs · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/admin/orgs \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Create an organization

Create an organization.

POST /api/v1/admin/orgs · Auth: superadmin

Request body

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/orgs \
  -H "Authorization: Bearer $SUPERADMIN_JWT" -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "contact_email": "it@acme.com"}'

Update an organization

Update org details (name, contact, industry, ...).

PATCH /api/v1/admin/orgs/{org_id} · Auth: superadmin

Sample request

curl -sX PATCH https://ragz.example.com/api/v1/admin/orgs/$ORG_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Delete an organization

Delete an organization.

DELETE /api/v1/admin/orgs/{org_id} · Auth: superadmin

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/admin/orgs/$ORG_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 204 No Content.

Set SSO domains for an organization

Set the email domains that auto-route to SSO for this org.

PUT /api/v1/admin/orgs/{org_id}/sso-domains · Auth: superadmin

Sample request

curl -sX PUT https://ragz.example.com/api/v1/admin/orgs/$ORG_ID/sso-domains \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Provider settings, models, secrets (superadmin)

Secrets (provider API keys, SMTP passwords, bot tokens, ...) are envelope-encrypted (AES-256-GCM) at rest and write-only through the API — PUT accepts a value and returns metadata only; there is no endpoint that ever returns a stored secret's plaintext.

Get / update provider settings

Non-secret provider configuration.

GET /api/v1/admin/settings · Auth: superadmin (settings.manage) PUT /api/v1/admin/settings · Auth: superadmin (settings.manage)

Sample request

curl -s https://ragz.example.com/api/v1/admin/settings \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Get / update email configuration

SMTP/SES email configuration.

GET /api/v1/admin/email · Auth: superadmin (settings.manage) PUT /api/v1/admin/email · Auth: superadmin (settings.manage)

Sample request

curl -s https://ragz.example.com/api/v1/admin/email \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Send a test email

Send a test email.

POST /api/v1/admin/email/test · Auth: superadmin (settings.manage)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/email/test \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

List registered models

List registered models.

GET /api/v1/admin/models · Auth: superadmin (models.read)

Sample request

curl -s https://ragz.example.com/api/v1/admin/models \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Register a model

Register a model (chat or embedding).

POST /api/v1/admin/models · Auth: superadmin (models.manage)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/models \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 201 Created.

Update / remove a model

Update / remove a model.

PATCH /api/v1/admin/models/{model_id} · Auth: superadmin (models.manage) DELETE /api/v1/admin/models/{model_id} · Auth: superadmin (models.manage)

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/admin/models/$MODEL_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• DELETE returns 204 No Content.

Browse the model catalog

Browse LiteLLM's known-model catalog.

GET /api/v1/admin/models/catalog · Auth: superadmin (models.read)

Sample request

curl -s https://ragz.example.com/api/v1/admin/models/catalog \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Force-refresh the model catalog

Force-refresh the catalog.

POST /api/v1/admin/models/catalog/refresh · Auth: superadmin (models.manage)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/models/catalog/refresh \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

List secret names

List stored secret names (never values).

GET /api/v1/admin/secrets · Auth: superadmin (secrets.manage)

Sample request

curl -s https://ragz.example.com/api/v1/admin/secrets \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Write a secret

Write a secret (write-only — never read back).

PUT /api/v1/admin/secrets/{name} · Auth: superadmin (secrets.manage)

Request body

Sample request

curl -sX PUT https://ragz.example.com/api/v1/admin/secrets/openai_api_key \
  -H "Authorization: Bearer $SUPERADMIN_JWT" -H "Content-Type: application/json" \
  -d '{"value": "sk-..."}'

Delete a secret

Delete a secret.

DELETE /api/v1/admin/secrets/{name} · Auth: superadmin (secrets.manage)

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/admin/secrets/openai_api_key \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 204 No Content.

Bot integrations (superadmin)

Bot tokens/signing secrets are write-only, same posture as secrets above. The inbound webhook routes themselves (POST /external/bots/{platform}/{webhook_id}) are public — their auth is signature verification, not a bearer token.

Connect a bot integration

Connect a Telegram/Slack/Discord bot to a workspace.

POST /api/v1/admin/bots · Auth: superadmin (integrations.manage)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/bots \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 201 Created.

List bot integrations

List configured bot integrations.

GET /api/v1/admin/bots · Auth: superadmin (integrations.manage)

Sample request

curl -s https://ragz.example.com/api/v1/admin/bots \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Enable / disable a bot integration

Enable/disable a bot integration.

PATCH /api/v1/admin/bots/{bot_id} · Auth: superadmin (integrations.manage)

Sample request

curl -sX PATCH https://ragz.example.com/api/v1/admin/bots/$BOT_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Remove a bot integration

Remove a bot integration.

DELETE /api/v1/admin/bots/{bot_id} · Auth: superadmin (integrations.manage)

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/admin/bots/$BOT_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 204 No Content.

API keys (superadmin)

See Authentication for POST / GET /api/v1/admin/api-keys and DELETE /api/v1/admin/api-keys/{key_id} — all superadmin-only.

SSO (superadmin)

Get / update SSO configuration

Platform OIDC SSO configuration.

GET /api/v1/admin/sso · Auth: superadmin PUT /api/v1/admin/sso · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/admin/sso \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Roles (custom role authoring)

Custom roles are superadmin-composable: a role template is a named bundle of the same granular permission strings (documents.upload, chat.generate, workspace.members.manage, ...) used throughout this API, so you can build roles narrower or broader than the built-in user / admin / superadmin tiers.

List role templates

List role templates.

GET /api/v1/admin/roles · Auth: admin+superadmin (roles.read)

Sample request

curl -s https://ragz.example.com/api/v1/admin/roles \
  -H "Authorization: Bearer $ADMIN_JWT"

Create a custom role template

Create a custom role template.

POST /api/v1/admin/roles · Auth: superadmin (roles.author)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/roles \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• Returns 201 Created.

Edit / delete a role template

Edit / delete a role template.

PATCH /api/v1/admin/roles/{role_template_id} · Auth: superadmin (roles.author) DELETE /api/v1/admin/roles/{role_template_id} · Auth: superadmin (roles.author)

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/admin/roles/$ROLE_TEMPLATE_ID \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Notes

• DELETE returns 204 No Content.

Activate a role template version

Activate a role template version.

POST /api/v1/admin/roles/{role_template_id}/activate · Auth: superadmin (roles.author)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/roles/$ROLE_TEMPLATE_ID/activate \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Roll back a role template

Roll back to a prior version.

POST /api/v1/admin/roles/{role_template_id}/rollback · Auth: superadmin (roles.author)

Sample request

curl -sX POST https://ragz.example.com/api/v1/admin/roles/$ROLE_TEMPLATE_ID/rollback \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Preview role change impact

Preview who a role change would affect.

GET /api/v1/admin/roles/{role_template_id}/impact · Auth: admin+superadmin (roles.read)

Sample request

curl -s https://ragz.example.com/api/v1/admin/roles/$ROLE_TEMPLATE_ID/impact \
  -H "Authorization: Bearer $ADMIN_JWT"

Users, groups, and workspace members (org admin)

List users

List users in your org.

GET /api/v1/users · Auth: admin+superadmin

Sample request

curl -s https://ragz.example.com/api/v1/users \
  -H "Authorization: Bearer $ADMIN_JWT"

Update a user

Activate/deactivate, change built-in role.

PATCH /api/v1/users/{user_id} · Auth: admin+superadmin

Sample request

curl -sX PATCH https://ragz.example.com/api/v1/users/$USER_ID \
  -H "Authorization: Bearer $ADMIN_JWT"

Assign a custom role

Assign a custom role template.

PUT /api/v1/users/{user_id}/custom-role · Auth: admin+superadmin

Sample request

curl -sX PUT https://ragz.example.com/api/v1/users/$USER_ID/custom-role \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• Returns 204 No Content.

List ACL groups

List ACL groups.

GET /api/v1/groups · Auth: admin+superadmin

Sample request

curl -s https://ragz.example.com/api/v1/groups \
  -H "Authorization: Bearer $ADMIN_JWT"

Create an ACL group

Create an ACL group.

POST /api/v1/groups · Auth: admin+superadmin

Sample request

curl -sX POST https://ragz.example.com/api/v1/groups \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• Returns 201 Created.

Delete an ACL group

Delete an ACL group.

DELETE /api/v1/groups/{group_id} · Auth: admin+superadmin

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/groups/$GROUP_ID \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• Returns 204 No Content.

Add / remove a group member

Add/remove a group member.

PUT /api/v1/groups/{group_id}/members/{user_id} · Auth: admin+superadmin DELETE /api/v1/groups/{group_id}/members/{user_id} · Auth: admin+superadmin

Sample request

curl -sX PUT https://ragz.example.com/api/v1/groups/$GROUP_ID/members/$USER_ID \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• Both return 204 No Content.

Add a member to a workspace

Add a member to a workspace.

POST /api/v1/workspaces/{workspace_id}/members · Auth: workspace.members.manage

Request body

Sample request

curl -sX POST https://ragz.example.com/api/v1/workspaces/$WORKSPACE_ID/members \
  -H "Authorization: Bearer $ADMIN_JWT" -H "Content-Type: application/json" \
  -d '{"user_id": "5b6c...-uuid", "role": "contributor"}'

Notes

• Returns 204 No Content.

List workspace members

List workspace members.

GET /api/v1/workspaces/{workspace_id}/members · Auth: workspace.members.read

Sample request

curl -s https://ragz.example.com/api/v1/workspaces/$WORKSPACE_ID/members \
  -H "Authorization: Bearer $ADMIN_JWT"

Change a workspace member's role

Change a member's workspace role.

PATCH /api/v1/workspaces/{workspace_id}/members/{user_id} · Auth: workspace.members.manage

Sample request

curl -sX PATCH https://ragz.example.com/api/v1/workspaces/$WORKSPACE_ID/members/$USER_ID \
  -H "Authorization: Bearer $ADMIN_JWT"

Remove a workspace member

Remove a workspace member.

DELETE /api/v1/workspaces/{workspace_id}/members/{user_id} · Auth: workspace.members.manage

Sample request

curl -sX DELETE https://ragz.example.com/api/v1/workspaces/$WORKSPACE_ID/members/$USER_ID \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• Returns 204 No Content.

Reports

Both routes take a scope query param — self, department, org, or platform — escalating the permission required in-handler: self is the floor everyone with chat access already holds; department and org need the matching reports.view.department / reports.view.org grant (auto-held by admins); platform is gated on the superadmin role directly, not a permission, so an org admin can never see cross-org data by acquiring a permission string.

Usage report

Usage/cost report, grouped by day/user/workspace/feature/model.

GET /api/v1/reports/usage · Auth: reports.view.self (floor)

Sample request

curl -s https://ragz.example.com/api/v1/reports/usage \
  -H "Authorization: Bearer $ADMIN_JWT"

Usage report (CSV export)

Same report as a CSV download.

GET /api/v1/reports/usage/export · Auth: reports.view.self (floor)

Sample request

curl -s "https://ragz.example.com/api/v1/reports/usage/export?scope=org&days=30&group_by=user" \
  -H "Authorization: Bearer $ADMIN_JWT" -o usage-report.csv

Audit

audit.read and audit.export are explicit, independently grantable permissions — not folded into a generic "admin" bucket — so an org can staff a read-only auditor role without handing out user/workspace management rights.

Audit log

Cursor-paginated, filterable audit log (own org; superadmin sees any org via org_id).

GET /api/v1/admin/audit · Auth: audit.read

Sample request

curl -s https://ragz.example.com/api/v1/admin/audit \
  -H "Authorization: Bearer $ADMIN_JWT"

Audit log export

Streamed NDJSON export of the audit log.

GET /api/v1/admin/audit/export · Auth: audit.export

Sample request

curl -s https://ragz.example.com/api/v1/admin/audit/export \
  -H "Authorization: Bearer $ADMIN_JWT" -o audit-log.ndjson

Quotas and platform ops

Org-level quota

Org-level token quota.

GET /api/v1/admin/orgs/{org_id}/quota · Auth: superadmin PUT /api/v1/admin/orgs/{org_id}/quota · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/admin/orgs/$ORG_ID/quota \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Per-user quota

Per-user token quota.

GET /api/v1/users/{user_id}/quota · Auth: admin+superadmin PUT /api/v1/users/{user_id}/quota · Auth: admin+superadmin

Sample request

curl -s https://ragz.example.com/api/v1/users/$USER_ID/quota \
  -H "Authorization: Bearer $ADMIN_JWT"

Notes

• PUT returns 204 No Content.

Org usage summary

Org usage summary.

GET /api/v1/admin/usage/summary · Auth: analytics.view

Sample request

curl -s https://ragz.example.com/api/v1/admin/usage/summary \
  -H "Authorization: Bearer $ADMIN_JWT"

Cross-org usage analytics

Cross-org usage analytics.

GET /api/v1/admin/usage/orgs · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/admin/usage/orgs \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Platform health

Platform health/ops status.

GET /api/v1/superadmin/health · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/superadmin/health \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Frontend error reports

Aggregated frontend error reports.

GET /api/v1/superadmin/client-errors · Auth: superadmin

Sample request

curl -s https://ragz.example.com/api/v1/superadmin/client-errors \
  -H "Authorization: Bearer $SUPERADMIN_JWT"

Message feedback queue

Review message thumbs-up/down feedback.

GET /api/v1/admin/feedback · Auth: admin+superadmin (feedback.review)

Sample request

curl -s https://ragz.example.com/api/v1/admin/feedback \
  -H "Authorization: Bearer $ADMIN_JWT"