Skip to main content

Overview

The DVARA Admin API is the control plane for a running deployment. Every resource the DVARA Flightdeck can edit — tenants, API keys, routes, policies, budgets, provider credentials, webhooks, MCP servers, audit events — is also available as a REST endpoint, so you can provision interactively from DVARA Flightdeck and automate the same actions from CI/CD, Terraform, or any other tooling that speaks HTTP. Both surfaces read and write the same underlying state, so a change made over the API is immediately visible in DVARA Flightdeck and vice versa.

You can use this API to​

  • Provision tenants and API keys from CI/CD when onboarding a new team or application, then revoke or rotate them without touching DVARA Flightdeck.
  • Roll out routes and policies as code — commit routes/*.yaml and policies/*.yaml to Git, dry-run them on every pull request with POST /v1/admin/policies/dry-run, and apply on merge via PUT /v1/admin/routes/{id} or POST /v1/admin/policies/{id}/status. Every change is versioned automatically and rollback is a single POST /v1/admin/routes/{id}/rollback call.
  • Manage provider credentials with BYOK — create tenant-scoped credentials, rotate them on a schedule, and revoke on compromise. Secrets are encrypted at rest with AES-256-GCM and the plaintext is never echoed back on read endpoints.
  • Enforce hard and soft budgets across the whole fleet with POST /v1/admin/budgets, and query current-period spend with GET /v1/admin/budgets/{id}/usage to power dashboards and alerts.
  • Export the whole configuration as a JSON snapshot with GET /v1/admin/config/export and replay it into another environment (staging, DR region, new cluster) with POST /v1/admin/config/import?mode=merge&dry_run=true. Every import is atomic — a failure at any point rolls back the whole request.
  • Query the audit event stream by tenant, event type, and time range to investigate incidents or hand evidence to compliance reviewers. CSV and JSON exports are available at /v1/admin/audit/events/export and /v1/admin/audit/events/export/json.

Key features​

Every Admin API operation shares the same guarantees:

  • Single source of truth. The Admin API and the DVARA Flightdeck read and write the same tenants, routes, policies, credentials, and audit trail. Provision from a script at 2 a.m., review the change in DVARA Flightdeck at 9, and the same audit event ties both together.
  • Versioned, rollback-friendly. Routes, policies, and prompt templates keep the last 10 versions with automatic incrementing, diff viewers in the UI, and a rollback endpoint that creates a new version restoring the old content.
  • Live propagation. Mutations flow out to every gateway instance within a few seconds — no restart, no deployment, no coordination step. A tenant metadata change fires a TENANT_METADATA_UPDATED audit event before the next LLM request finishes.
  • Tamper-evident audit. Every mutation — whether made from DVARA Flightdeck, the Admin API, or an automation script using a personal access token — emits a signed, hash-chained audit event with the actor identity, the changed fields, and the trace ID. Exports keep the signatures intact for downstream verification.
  • Role-based access control. Platform roles (owner, policy-admin, billing-admin) can act across every tenant; tenant roles (admin, developer, viewer) can only see and modify their own tenant's resources. A tenant-scoped caller that passes another tenant's tenant_id is always rejected with 403 (a TENANT_SCOPE_VIOLATION audit event); only an omitted parameter is silently narrowed to the caller's own tenant.

Getting started​

Prerequisites​

  • A running DVARA Flightdeck reachable on port 8090 (default). See the Quickstart for the Docker Compose setup that brings the DVARA Flightdeck and the LLM proxy up together. The gateway requires a valid license key and a PostgreSQL instance.
  • A Personal Access Token issued from the DVARA Flightdeck (Settings → Tokens) for automation, or an OIDC JWT / SAML session if your deployment uses a corporate identity provider. See the dedicated Authentication page for how to create, rotate, and revoke PATs.

Authentication​

Every /v1/admin/* call requires an authenticated session. For automation, pass a Personal Access Token as a Bearer header:

Authorization: Bearer dvara_pat_<your-token>

See the Authentication page for OIDC and SAML configurations.

Minimal end-to-end example​

Create a tenant, issue it an API key, and provision a route that sends every gpt-* request to OpenAI — end to end with four curl calls:

export DVARA_ADMIN=http://localhost:8090
export DVARA_PAT=dvara_pat_...

# 1. Create a tenant
curl -s -X POST $DVARA_ADMIN/v1/admin/tenants \
  -H "Authorization: Bearer $DVARA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"id":"acme-corp","name":"Acme Corp","status":"ACTIVE"}'

# 2. Issue an API key — plaintext is returned exactly once
curl -s -X POST $DVARA_ADMIN/v1/admin/tenants/acme-corp/keys \
  -H "Authorization: Bearer $DVARA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name":"production-key"}'

# 3. Create a route that sends gpt-* traffic to OpenAI
curl -s -X POST $DVARA_ADMIN/v1/admin/routes \
  -H "Authorization: Bearer $DVARA_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "id":"gpt-route",
    "model_pattern":"gpt*",
    "strategy":"model-prefix",
    "providers":[{"provider":"openai"}]
  }'

# 4. Confirm — the new tenant appears in the list
curl -s $DVARA_ADMIN/v1/admin/tenants \
  -H "Authorization: Bearer $DVARA_PAT"

That's it — the LLM data plane on port 8080 is now ready to serve Acme Corp's requests through the new route, rate-limited and billed under the new API key.

Open the DVARA Flightdeck at http://localhost:8090 and you'll see the tenant under Tenants, the key under Tenants → Acme Corp → Keys, and the route under Routes. The three mutating calls each emit a resource-specific audit event with your PAT's actor identity — TENANT_CREATED, API_KEY_CREATED, and ROUTE_CREATED — visible under Audit (the fourth call is a read and emits nothing).

What's in this reference​

  • Authentication — personal access tokens, OIDC, SAML, and the RBAC model.
  • Try the API — how to aim the interactive Try it panel at a running deployment.
  • Specifications — every endpoint grouped by resource (Tenants, Routes, Policies, Budgets, Credentials, Webhooks, MCP Servers, Audit, Config) with request / response schemas and live Try-it panels.

Scope of this reference​

This spec covers the core GitOps surface that most automation pipelines need. The full Admin API has additional endpoints for compliance reports, cost forecasts, chargeback, prompt templates, eval pipelines, guardrail plugins, MCP approvals, and session management — those are documented with end-to-end examples on the DVARA Flightdeck feature pages. The spec will grow over time as more of those surfaces move into the machine-readable contract.

REST-only administrative endpoints​

A small set of admin operations are available only via the REST API — there is no corresponding DVARA Flightdeck page, by design. The cases below each have a specific reason the UI would add more noise than value; the sections explain the rationale and show how to drive each endpoint from a script.

Output schemas — /v1/admin/schemas​

Registered JSON schemas for structured outputs. Clients can reference schemas by ID (response_format: {type: "json_schema", json_schema: {id: "..."}}) instead of sending the full schema inline on every request. Schemas are versioned config that usually lives in source control next to the apps that consume them, so CRUD via CI/CD beats a web UI.

# Create
curl -X POST $DVARA_ADMIN/v1/admin/schemas \
  -H "Authorization: Bearer $DVARA_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "person-v1",
    "schema": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "age":  {"type": "integer"}
      },
      "required": ["name", "age"]
    }
  }'

# List all
curl $DVARA_ADMIN/v1/admin/schemas \
  -H "Authorization: Bearer $DVARA_PAT"

# Get one
curl $DVARA_ADMIN/v1/admin/schemas/person-v1 \
  -H "Authorization: Bearer $DVARA_PAT"

# Update (replaces the whole schema body)
curl -X PUT $DVARA_ADMIN/v1/admin/schemas/person-v1 \
  -H "Authorization: Bearer $DVARA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"schema": { /* updated schema */ }}'

# Delete
curl -X DELETE $DVARA_ADMIN/v1/admin/schemas/person-v1 \
  -H "Authorization: Bearer $DVARA_PAT"

See Structured Outputs → Inline schema vs. registered schema for when to register versus when to send inline.

Priority admission stats — /v1/admin/priority/stats​

Point-in-time snapshot of concurrent-request counts and per-tier throttle thresholds. For live dashboards, alerting, and historical trends use the Prometheus counters (gateway_priority_requests_total{tenant, tier}, gateway_priority_throttled_total{tenant, tier}) instead — they carry per-tenant cardinality and roll up cleanly in Grafana. This endpoint exists for runbook scripts and capacity spot-checks where pulling once and reading the JSON is simpler than a Prometheus query.

curl $DVARA_ADMIN/v1/admin/priority/stats \
  -H "Authorization: Bearer $DVARA_PAT"

Response:

{
  "object": "priority_stats",
  "data": {
    "currentConcurrent": 17,
    "maxConcurrent": 1000,
    "perTierConcurrent": {"premium": 5, "standard": 10, "bulk": 2},
    "perTierThresholdPct": {"premium": 100, "standard": 80, "bulk": 50}
  }
}

See Routing → SLA-aware priority routing for how admission is gated and how to tune thresholds.

Token usage — /v1/admin/token-usage​

Per-request token records (input tokens, output tokens, model, provider, tenant, API key, timestamp). The Flightdeck Cost Dashboard aggregates these same records multiplied by the pricing table into dollar figures — that's the right surface for 95% of users. This endpoint is for pricing audits, cost-per-token experiments, and reconciling a disputed tenant invoice where the raw records matter.

List records with filters:

curl "$DVARA_ADMIN/v1/admin/token-usage?tenantId=acme&model=gpt-4o&from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $DVARA_PAT"

All filter parameters (all optional):

  • tenantId — restrict to one tenant
  • apiKey — restrict to one API key
  • model — restrict to one model
  • from, to — ISO-8601 date range

Summary aggregates:

curl "$DVARA_ADMIN/v1/admin/token-usage/summary?tenantId=acme&from=2026-04-01&to=2026-04-30" \
  -H "Authorization: Bearer $DVARA_PAT"

Response rolls the raw records up by model and provider with total input tokens, total output tokens, and call count.

See Flightdeck → Cost Management → Token-level data for the "aggregate via UI, detail via API" rationale.

Last updated on