REST API

!!! tip 'Use role-scoped tokens' Create service tokens with minimal scopes for automation and integrations.

!!! note 'Rate limits' Admin API enforces per-client rate-limits managed via the gateway configuration.

!!! warning 'Audit queries may be large' Use pagination and filters when querying audit logs to avoid long-running requests.

Common endpoints

Example: Create a user

# (1)
import requests
token = 'Bearer <ADMIN_TOKEN>'
r = requests.post('https://admin.example/api/users', headers={'Authorization': token}, json={'username':'alice'})
print(r.json())

// (1)
const fetch = require('node-fetch')
const res = await fetch('https://admin.example/api/users', { method: 'POST', headers: { Authorization: 'Bearer <ADMIN_TOKEN>', 'Content-Type': 'application/json' }, body: JSON.stringify({ username: 'alice' }) })
console.log(await res.json())

# (1)
curl -X POST https://admin.example/api/users -H 'Authorization: Bearer <ADMIN_TOKEN>' -H 'Content-Type: application/json' -d '{"username":"alice"}'

1. Use scoped tokens and role assertions; avoid admin tokens in automation when possible

mermaid graph LR AdminUI -->|API Calls| API API --> AuthService API --> Storage API --> Plugins API --> Audit

Audit API: filtering

!!! note 'Pagination' The Admin API uses cursor-based pagination for large datasets. Check response for ++next_cursor++ field.

??? note 'Advanced: webhook integrations' The Admin API supports webhook delivery for events. Use signed payloads and retry policies.