Ana içeriğe geç

REST API

The full OpenAPI 3.1 description is served by every instance at GET /openapi.yaml (source: internal/api/openapi.yaml). A test keeps it in sync with the router. This page covers the conventions.

Resources​

PathOperations
/v1/tenantslist (filters: status, plan, parent_id, label=k=v, include_deleted), create
/v1/tenants/{id}get, PATCH, DELETE (accepts an ID or a slug; ?force=true skips the deletion grace period)
/v1/tenants/{id}/suspend · /resume · /restore · /retry-provisioninglifecycle transitions
/v1/tenants/{id}/schedule[/{action}]scheduled actions: list, schedule, cancel
/v1/tenants/{id}/domains[/{hostname}[/verify]], /v1/domains/resolve, /v1/domains/checkcustom domains
/v1/tenants/{id}/domains/{hostname}/certificatestatus of the managed certificate of a domain
/v1/tenants/{id}/api-keys[/{key}], /v1/api-keys[/{key}]tenant and platform API keys
/v1/tenants/{id}/webhooks[/...]tenant webhooks and their delivery log
/v1/tenants/{id}/ssothe tenant's SSO connection (OIDC or SAML)
/v1/tenants/{id}/roles[/{role}]tenant roles: list (built-in and custom), get, PUT, DELETE
/v1/tenants/{id}/groups[/{group}[/members/{member}]]groups: CRUD, PUT/DELETE a member
/v1/tenants/{id}/exportdata export of the tenant
/v1/audit, /v1/tenants/{id}/auditthe audit trail: newest first, filter by actor, type, time
/v1/tenants/{id}/childrendirect children
/v1/tenants/{id}/entitlementseffective features and limits (how they are computed)
/v1/tenants/{id}/plan-revisionPUT {"revision": n} pins the tenant to a plan revision (0 unpins)
/v1/tenants/{id}/movePOST {"region": "us"} moves the tenant to another region (platform only)
/v1/tenants/{id}/cloneclone a tenant
/v1/tenants/{id}/maintenancePOST starts, DELETE ends a maintenance window
/v1/tenants/{id}/healththe tenant's health score
/v1/tenant-templates[/{template}]tenant templates: list, get, PUT, DELETE; use with "template" on create
/v1/tenants/{id}/members[/{member}]list, add/invite, change role or accept, remove
/v1/tenants/{id}/usage[/{metric}[/history]]current counters and limits; POST {"delta": n} to record usage; past periods (usage periods)
/v1/tenants/{id}/scim/v2/...SCIM 2.0 Users and Groups for identity providers
/v1/plans[/{id}], /v1/plans/{id}/revisionsCRUD; recorded revisions
/v1/rollouts[/{feature}]feature rollouts: list, get, PUT, DELETE (platform only)
/v1/regionsthe configured regions (tenants.regions)
/v1/actionsevery built-in action, for building custom roles
/v1/eventsthe event log (after, tenant_id, type glob, limit)
/v1/events/replayredeliver a time range of events to one subscription
/v1/event-schemas[/{type}[/{version}]]the event schema registry
/v1/dead-letters[/{id}[/replay]]inspect, replay or discard failed deliveries
/v1/pluginsloaded plugin instances and their registrations
/v1/admin/reloadPOST reloads the configuration file (platform only, config:reload)
/v1/me, /v1/me/memberships, /v1/me/password, /v1/me/mfa/...the authenticated caller, two-factor authentication
/v1/me/passkeys[/{passkey}], /v1/me/passkeys/register/begin · /finishthe caller's passkeys
/v1/me/sessions[/{session}], /v1/users/{id}/sessions[/{session}]list and revoke a user's sessions (DELETE /v1/users/{id}/sessions revokes all)
/v1/auth/brandingpublic branding for sign-in pages (?tenant= or ?host=; no auth)
/v1/me/email, /v1/auth/email-change/confirmemail change with confirmation link
/v1/auth/magic-linksign-in links (grant_type: magic_link at /v1/auth/token)
/v1/auth/social, /v1/auth/social/{provider}/start · /callbacksocial login (no auth)
/v1/me/export, /v1/me/impersonation-consentthe caller's data export, impersonation consent
/v1/users[/{id}] and /disable, /enable, /password, /invitation, /sessions, /mfa, /membershipsuser administration (users)
/v1/users/{id}/export · /erase · /impersonateexport, erasure and impersonation
/v1/oauth-clients[/{client}[/rotate-secret]]applications of the OpenID provider (platform only)
/v1/signing-keys, /rotate, /{kid}token signing keys
/v1/auth/token, /logout, /password-reset[/confirm], /invitations/accept, /passkey/begin · /finishsign-in and account recovery (no auth, rate limited)
/v1/auth/sso/start · /callback · /discover, /v1/auth/sso/saml/{tenant}/metadata · /acstenant SSO (no auth)
/oauth/authorize, /login, /consent, /token, /userinfo, /logoutthe OpenID provider endpoints (no auth; /oauth/login and /oauth/token are rate limited)
/.well-known/openid-configuration, /.well-known/jwks.jsonverify Tenarium tokens in your services
/v1/plugins/{instance}/..., /v1/plugins/{instance}/public/...routes contributed by plugins (public ones without auth)
/healthz, /readyz, /metrics, /openapi.yaml, /ui/operations (no auth)

Conventions​

Errors always have this shape:

{"error": {"code": "validation_failed", "message": "must be 1-200 characters", "field": "name"}}
StatusCode
400reload_failed, validation_failed, invalid_json, invalid_body, invalid_idempotency_key, invalid_token, tenant_required, not_a_user, password_login_unavailable
401unauthorized, invalid_credentials, mfa_required, invalid_otp, passkey_rejected
403forbidden, sso_required, consent_required (impersonation without a valid consent code)
404not_found
409already_exists, invalid_transition, unknown_subscription, active_key
412version_conflict
422rejected (a plugin hook refused), idempotency_key_reused, verification_failed (domain TXT record missing)
429quota_exceeded (field holds the metric; X-Quota-Limit the limit), account_locked, rate_limited
502replay_failed
503maintenance (a tenant-scoped write during a maintenance window; Retry-After is set)

Optimistic concurrency. Tenants, plans and members carry a version, returned as ETag: "3". Send If-Match: "3" with PATCH to fail with 412 if the resource changed in the meantime.

Idempotency. POST requests may carry Idempotency-Key. The first response (unless it is a 5xx) is stored for 24 hours per caller and path; retrying with the same key and body returns it again with Idempotent-Replayed: true. Reusing a key with a different body returns 422.

Pagination. Lists return {"items": [...], "next": "<cursor>"}; pass after=<cursor> to get the next page. next is absent on the last page.

Partial updates. In PATCH /v1/tenants/{id}, labels, features, limits and add_ons replace the whole map or list, and settings is an RFC 7386 merge patch (null deletes a key). region cannot be patched; use POST /v1/tenants/{id}/move. In PATCH /v1/plans/{id}, "grandfather": true keeps the plan's current tenants on the old values (see plan revisions).

Request IDs. Every response has X-Request-ID (your value is echoed back if you send one). It appears in error logs.

Example session​

API=http://localhost:8080; AUTH="Authorization: Bearer $TENARIUM_API_KEY"

curl -sX POST $API/v1/plans -H "$AUTH" -d '{"id":"pro","name":"Pro","limits":{"members":50,"api_calls":100000}}'
curl -sX POST $API/v1/tenants -H "$AUTH" -H "Idempotency-Key: $(uuidgen)" \
-d '{"slug":"acme","name":"Acme","plan":"pro","labels":{"region":"eu"}}'
curl -sX POST $API/v1/tenants/acme/members -H "$AUTH" -d '{"email":"[email protected]","role":"owner"}'
curl -sX POST $API/v1/tenants/acme/usage/api_calls -H "$AUTH" -d '{"delta":1}'
curl -s "$API/v1/events?tenant_id=$(curl -s $API/v1/tenants/acme -H "$AUTH" | jq -r .id)" -H "$AUTH"