API Reference

Overview of the Vaultaris REST API — endpoints, authentication, response conventions, and rate limiting.

Base URL: https://{your-vaultaris-host}/api/v1. Interactive API docs at /api/v1/docs (Scalar UI). OpenAPI 3.1 spec at /api/v1/docs/openapi.json.

Authentication

All authenticated endpoints require:

Authorization: Bearer {access_token}

Obtain tokens via the OAuth 2.0 endpoints (/oauth/token). Service-to-service calls using API keys use:

X-Api-Key: {api_key}

Response format

Success:

{ "data": { ... } }

Paginated success:

{ "data": [...], "meta": { "page": 1, "per_page": 20, "total": 143 } }

Error:

{ "error": "not_found", "message": "Tenant not found", "status": 404 }

Pagination

Query params: page (default 1), per_page (default 20, max 100).

Rate limiting

120 requests / 60 s per IP. Redis-backed sliding window. Returns 429 Too Many Requests with Retry-After header. Configurable via RATE_LIMIT_MAX_REQUESTS / RATE_LIMIT_WINDOW_SECS.

Endpoint catalogue

Health & Observability

Method	Path	Auth	Description
`GET`	`/health`	None	Basic liveness check
`GET`	`/ready`	None	Readiness (load balancer probe)
`GET`	`/live`	None	Liveness (Kubernetes probe)
`GET`	`/health/detailed`	None	Component status (DB, Redis, email)
`GET`	`/metrics`	None	Prometheus metrics

OIDC Discovery

Method	Path	Auth	Description
`GET`	`/.well-known/openid-configuration`	None	OIDC discovery document
`GET`	`/.well-known/jwks.json`	None	Public JWK set

OAuth 2.0

Method	Path	Auth	Description
`GET`	`/oauth/authorize`	None	Authorization endpoint (redirect)
`POST`	`/oauth/token`	Client creds	Token endpoint (all grant types)
`POST`	`/oauth/revoke`	Client creds	Revoke access or refresh token
`POST`	`/oauth/introspect`	Client creds	Token introspection
`GET`	`/oauth/userinfo`	Bearer	UserInfo endpoint
`GET`	`/oauth/consent/{request_id}`	None	Get pending consent details
`POST`	`/oauth/consent/{request_id}/approve`	Bearer	Approve consent
`POST`	`/oauth/consent/{request_id}/deny`	Bearer	Deny consent

Setup wizard

Method	Path	Auth	Description
`GET`	`/setup/check`	None	Check if setup is needed
`GET`	`/setup/status`	None	Detailed setup status
`POST`	`/setup/preview-license`	None	Preview license tier before activating
`POST`	`/setup/webauthn-challenge`	None	Get passkey challenge for admin enrollment
`POST`	`/setup`	None	Complete initial setup

Tenants

Method	Path	Auth	Description
`GET`	`/api/v1/tenants`	Bearer	List accessible tenants
`POST`	`/api/v1/tenants`	Bearer	Create tenant
`GET`	`/api/v1/tenants/{id}`	Bearer	Get tenant details
`PUT`	`/api/v1/tenants/{id}`	Bearer	Update tenant
`DELETE`	`/api/v1/tenants/{id}`	Bearer	Soft-delete tenant
`GET`	`/api/v1/tenants/{id}/license`	Bearer	Get license details
`GET`	`/api/v1/tenants/{id}/license/limits/{resource}`	Bearer	Check limit for a resource type
`GET`	`/api/v1/tenants/{id}/frozen`	Bearer	List frozen resources
`GET`	`/api/v1/tenants/{id}/statistics/overview`	Bearer	Overview stats
`GET`	`/api/v1/tenants/{id}/statistics/authentication`	Bearer	Auth attempts, success rate, time series
`GET`	`/api/v1/tenants/{id}/statistics/sessions`	Bearer	Session stats by device, location
`GET`	`/api/v1/tenants/{id}/statistics/security`	Bearer	Security events, locked accounts
`GET`	`/api/v1/tenants/{id}/statistics/dashboard`	Bearer	Combined dashboard summary
`GET`	`/api/v1/tenants/{id}/keys`	Bearer	List signing keys
`POST`	`/api/v1/tenants/{id}/keys/rotate`	Bearer	Rotate signing keys

Hosted tenants

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{host_id}/hosted-tenants/capability`	Bearer	Hosting capability + live count
`GET`	`/api/v1/tenants/{host_id}/hosted-tenants`	Bearer	List hosted tenants
`POST`	`/api/v1/tenants/{host_id}/hosted-tenants`	Bearer	Provision hosted tenant
`PATCH`	`/api/v1/tenants/{host_id}/hosted-tenants/{id}/status`	Bearer	Set status (active, suspended, archived)
`GET`	`/api/v1/tenants/{host_id}/hosted-tenants/{id}/stats`	Bearer	Aggregate stats (no PII)

Users

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/users`	Bearer	List users (paginated)
`POST`	`/api/v1/tenants/{id}/users`	Bearer	Create user
`GET`	`/api/v1/tenants/{id}/users/{uid}`	Bearer	Get user details
`PUT`	`/api/v1/tenants/{id}/users/{uid}`	Bearer	Update user profile
`DELETE`	`/api/v1/tenants/{id}/users/{uid}`	Bearer	Soft-delete user
`POST`	`/api/v1/tenants/{id}/users/{uid}/restore`	Bearer	Restore soft-deleted user
`GET`	`/api/v1/tenants/{id}/users/{uid}/roles`	Bearer	List user's roles
`POST`	`/api/v1/tenants/{id}/users/{uid}/roles`	Bearer	Assign role to user
`DELETE`	`/api/v1/tenants/{id}/users/{uid}/roles/{role_id}`	Bearer	Remove role from user
`GET`	`/api/v1/tenants/{id}/users/{uid}/groups`	Bearer	List user's groups
`POST`	`/api/v1/tenants/{id}/users/{uid}/groups`	Bearer	Add user to group
`DELETE`	`/api/v1/tenants/{id}/users/{uid}/groups/{group_id}`	Bearer	Remove user from group
`GET`	`/api/v1/tenants/{id}/users/{uid}/sessions`	Bearer	List user's sessions
`DELETE`	`/api/v1/tenants/{id}/users/{uid}/sessions`	Bearer	Revoke all user sessions
`GET`	`/api/v1/tenants/{id}/users/{uid}/devices`	Bearer	List registered devices
`GET`	`/api/v1/users/{uid}/tenants`	Bearer	Cross-tenant query for a user

Devices

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/users/{uid}/devices`	Bearer	List devices (trusted, untrusted, revoked)
`GET`	`/api/v1/tenants/{id}/users/{uid}/devices/{device_id}`	Bearer	Device details
`POST`	`/api/v1/tenants/{id}/users/{uid}/devices/{device_id}/trust`	Bearer	Mark device trusted
`DELETE`	`/api/v1/tenants/{id}/users/{uid}/devices/{device_id}`	Bearer	Revoke device
`GET`	`/api/v1/tenants/{id}/users/{uid}/devices/{device_id}/sessions`	Bearer	Session history for device

Roles

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/roles`	Bearer	List roles
`POST`	`/api/v1/tenants/{id}/roles`	Bearer	Create role
`GET`	`/api/v1/tenants/{id}/roles/{role_id}`	Bearer	Get role
`PUT`	`/api/v1/tenants/{id}/roles/{role_id}`	Bearer	Update role
`DELETE`	`/api/v1/tenants/{id}/roles/{role_id}`	Bearer	Soft-delete role
`POST`	`/api/v1/tenants/{id}/roles/{role_id}/restore`	Bearer	Restore soft-deleted role
`GET`	`/api/v1/tenants/{id}/roles/{role_id}/permissions`	Bearer	List role's permissions
`POST`	`/api/v1/tenants/{id}/roles/{role_id}/permissions`	Bearer	Add permission to role
`DELETE`	`/api/v1/tenants/{id}/roles/{role_id}/permissions/{perm_id}`	Bearer	Remove permission from role

Permissions

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/permissions`	Bearer	List permissions
`POST`	`/api/v1/tenants/{id}/permissions`	Bearer	Create permission
`GET`	`/api/v1/tenants/{id}/permissions/{perm_id}`	Bearer	Get permission
`PUT`	`/api/v1/tenants/{id}/permissions/{perm_id}`	Bearer	Update permission
`DELETE`	`/api/v1/tenants/{id}/permissions/{perm_id}`	Bearer	Soft-delete permission
`POST`	`/api/v1/tenants/{id}/permissions/{perm_id}/restore`	Bearer	Restore soft-deleted permission

Groups

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/groups`	Bearer	List groups
`POST`	`/api/v1/tenants/{id}/groups`	Bearer	Create group
`GET`	`/api/v1/tenants/{id}/groups/{group_id}`	Bearer	Get group
`PUT`	`/api/v1/tenants/{id}/groups/{group_id}`	Bearer	Update group
`DELETE`	`/api/v1/tenants/{id}/groups/{group_id}`	Bearer	Delete group
`POST`	`/api/v1/tenants/{id}/groups/{group_id}/restore`	Bearer	Restore soft-deleted group
`GET`	`/api/v1/tenants/{id}/groups/{group_id}/members`	Bearer	List members
`GET`	`/api/v1/tenants/{id}/groups/{group_id}/roles`	Bearer	List group roles
`POST`	`/api/v1/tenants/{id}/groups/{group_id}/roles`	Bearer	Assign role to group
`DELETE`	`/api/v1/tenants/{id}/groups/{group_id}/roles/{role_id}`	Bearer	Remove role from group
`GET`	`/api/v1/tenants/{id}/groups/{group_id}/login-providers`	Bearer	List IdP allowlist

Applications

Applications scope OAuth clients, IdPs, roles, groups, permissions, and ABAC policies per-service. Each resource type has a full link/unlink + create pattern (~40 endpoints total).

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/applications`	Bearer	List applications
`POST`	`/api/v1/tenants/{id}/applications`	Bearer	Create application
`GET`	`/api/v1/tenants/{id}/applications/{app_id}`	Bearer	Get application
`PUT`	`/api/v1/tenants/{id}/applications/{app_id}`	Bearer	Update application
`DELETE`	`/api/v1/tenants/{id}/applications/{app_id}`	Bearer	Delete application
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/clients`	Bearer	Link/unlink/create OAuth clients
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/roles`	Bearer	Link/unlink/create roles
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/groups`	Bearer	Link/unlink/create groups
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/permissions`	Bearer	Link/unlink/create permissions
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/identity-providers`	Bearer	Link/unlink/create IdPs
`GET/POST/DELETE`	`/api/v1/tenants/{id}/applications/{app_id}/policies`	Bearer	Link/unlink/create ABAC policies

OAuth Clients

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/clients`	Bearer	List OAuth clients
`POST`	`/api/v1/tenants/{id}/clients`	Bearer	Register OAuth client
`GET`	`/api/v1/tenants/{id}/clients/{client_id}`	Bearer	Get client config
`PUT`	`/api/v1/tenants/{id}/clients/{client_id}`	Bearer	Update client
`DELETE`	`/api/v1/tenants/{id}/clients/{client_id}`	Bearer	Revoke client
`POST`	`/api/v1/tenants/{id}/clients/{client_id}/secret`	Bearer	Regenerate client secret

Identity Providers

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/identity-providers`	Bearer	List IdPs
`POST`	`/api/v1/tenants/{id}/identity-providers`	Bearer	Create IdP
`GET`	`/api/v1/tenants/{id}/identity-providers/{provider_id}`	Bearer	Get IdP
`PUT`	`/api/v1/tenants/{id}/identity-providers/{provider_id}`	Bearer	Update IdP
`DELETE`	`/api/v1/tenants/{id}/identity-providers/{provider_id}`	Bearer	Delete IdP
`GET`	`/api/v1/tenants/{id}/identity-providers/login`	None	List login-enabled IdPs (public)
`GET`	`/api/v1/tenants/{id}/identity-providers/{provider_id}/authorize`	None	Get authorization URL

Sessions

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/sessions`	Bearer	List all tenant sessions
`DELETE`	`/api/v1/tenants/{id}/sessions/{session_id}`	Bearer	Revoke session
`GET`	`/api/v1/sessions/global/{token}`	None	Validate global session
`DELETE`	`/api/v1/sessions/global/{token}`	Bearer	Revoke global session
`POST`	`/api/v1/sessions/global/{token}/transfer`	Bearer	Create domain transfer token
`POST`	`/api/v1/sessions/transfer/redeem`	None	Redeem transfer token
`GET`	`/api/v1/sessions/global/me`	Bearer	List current user's global sessions

API Keys

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/api-keys`	Bearer	List API keys
`POST`	`/api/v1/tenants/{id}/api-keys`	Bearer	Create API key
`GET`	`/api/v1/tenants/{id}/api-keys/{key_id}`	Bearer	Get API key details
`PUT`	`/api/v1/tenants/{id}/api-keys/{key_id}`	Bearer	Update API key
`DELETE`	`/api/v1/tenants/{id}/api-keys/{key_id}`	Bearer	Delete API key
`POST`	`/api/v1/tenants/{id}/api-keys/{key_id}/revoke`	Bearer	Revoke API key
`GET`	`/api/v1/api-keys/me`	API Key	Current key's identity
`POST`	`/api/v1/api-keys/authorize`	API Key	RBAC + ABAC authorization check

MFA — TOTP

Method	Path	Auth	Description
`POST`	`/api/v1/mfa/totp/setup`	Bearer	Begin TOTP enrollment (returns QR secret)
`POST`	`/api/v1/mfa/totp/verify`	Bearer	Complete TOTP enrollment
`POST`	`/api/v1/mfa/totp/{user_id}/verify`	Bearer	Verify TOTP code (MFA challenge)
`DELETE`	`/api/v1/mfa/totp/{user_id}`	Bearer	Disable TOTP for user

MFA — WebAuthn / Passkeys

Method	Path	Auth	Description
`POST`	`/api/v1/mfa/webauthn/register/begin`	Bearer	Begin passkey registration
`POST`	`/api/v1/mfa/webauthn/register/complete`	Bearer	Complete passkey registration
`POST`	`/api/v1/mfa/webauthn/authenticate/begin`	Bearer	Begin passkey authentication
`POST`	`/api/v1/mfa/webauthn/authenticate/complete`	Bearer	Complete passkey authentication
`GET`	`/api/v1/mfa/webauthn/credentials`	Bearer	List registered passkeys
`DELETE`	`/api/v1/mfa/webauthn/credentials/{credential_id}`	Bearer	Remove passkey
`POST`	`/api/v1/auth/passkey/challenge`	None	Get challenge for passwordless login
`POST`	`/api/v1/auth/passkey/login`	None	Authenticate with passkey (no username needed)

ABAC Policies

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/policies`	Bearer	List policies
`POST`	`/api/v1/tenants/{id}/policies`	Bearer	Create policy
`GET`	`/api/v1/tenants/{id}/policies/{policy_id}`	Bearer	Get policy
`PUT`	`/api/v1/tenants/{id}/policies/{policy_id}`	Bearer	Update policy
`DELETE`	`/api/v1/tenants/{id}/policies/{policy_id}`	Bearer	Delete policy
`POST`	`/api/v1/tenants/{id}/policies/evaluate`	Bearer	Evaluate policies for a context
`GET`	`/api/v1/tenants/{id}/policies/conditions-schema`	Bearer	Schema for UI autocomplete
`GET`	`/api/v1/tenants/{id}/users/{uid}/policies/check`	Bearer	Quick access check for user

Audit Log

Method	Path	Auth	Description
`GET`	`/api/v1/tenants/{id}/audit`	Bearer	List audit entries (filterable by action, resource_type, actor_id)
`GET`	`/api/v1/tenants/{id}/audit/{entry_id}`	Bearer	Get audit entry detail

Password & Email

Method	Path	Auth	Description
`POST`	`/api/v1/auth/password-reset`	None	Request password reset (always 200)
`POST`	`/api/v1/auth/password-reset/validate`	None	Validate reset token
`POST`	`/api/v1/auth/password-reset/complete`	None	Set new password
`POST`	`/api/v1/auth/email-verification/resend`	Bearer	Resend verification email
`POST`	`/api/v1/auth/email-verification/verify`	None	Verify email via token

Method	Path	Auth	Description
`GET`	`/api/v1/hosted/{slug}/config`	None	Tenant branding + auth methods (public)
`POST`	`/api/v1/hosted/{slug}/mfa/verify`	None	Verify MFA code after password grant
`GET`	`/api/v1/hosted/{slug}/providers/{id}/auth-url`	None	Get IdP redirect URL
`GET`	`/api/v1/hosted/{slug}/idp-callback`	None	IdP OAuth callback

Integration API (server-to-server)

Method	Path	Auth	Description
`POST`	`/api/v1/integration/token/validate`	Bearer	Validate access token, get roles/permissions
`POST`	`/api/v1/tenants/{id}/integration/check-permission`	Bearer	RBAC + ABAC permission check
`POST`	`/api/v1/tenants/{id}/integration/batch-check-permissions`	Bearer	Batch permission checks
`GET`	`/api/v1/integration/session/validate`	Bearer	Validate session token
`GET`	`/api/v1/tenants/{id}/integration/users/{uid}`	Bearer	User info for external integrations

Kubernetes

Method	Path	Auth	Description
`POST`	`/api/v1/kubernetes/token-review`	Service token	K8s TokenReview (authn webhook)
`POST`	`/api/v1/kubernetes/subject-access-review`	Service token	K8s SubjectAccessReview (authz webhook)

Plugins

Method	Path	Auth	Description
`GET`	`/api/v1/admin/plugins`	Bearer	List installed plugins
`POST`	`/api/v1/admin/plugins`	Bearer	Install plugin
`GET`	`/api/v1/admin/plugins/{id}`	Bearer	Get plugin details
`DELETE`	`/api/v1/admin/plugins/{id}`	Bearer	Uninstall plugin
`POST`	`/api/v1/admin/plugins/{id}/activate`	Bearer	Activate plugin globally
`GET`	`/api/v1/tenants/{id}/plugins`	Bearer	List plugins active for tenant
`POST`	`/api/v1/tenants/{id}/plugins/{plugin_id}/enable`	Bearer	Enable plugin for tenant
`POST`	`/api/v1/tenants/{id}/plugins/{plugin_id}/disable`	Bearer	Disable plugin for tenant
`PUT`	`/api/v1/tenants/{id}/plugins/{plugin_id}/config`	Bearer	Update plugin config for tenant
`GET`	`/api/v1/tenants/{id}/plugins/{plugin_id}/health`	Bearer	Plugin health check
`GET`	`/api/v1/tenants/{id}/plugins/active-schemas`	Bearer	Merged config schema for UI rendering

Webhooks (inbound, plugin-defined)

Method	Path	Auth	Description
`*`	`/webhook/{plugin_slug}/{tenant_id}/{*rest}`	HMAC sig	Route to plugin webhook handler