Skip to main content

Admin Control Plane API Reference

The GoRoute Admin Control Plane (/admin/v1/*) provides unified APIs for tenant organization onboarding, multi-tenant RBAC, virtual key issuance, encrypted credential vault management, dynamic model routing, security guardrails, FinOps ledgers, and health probing.

[!NOTE] All admin routes require authentication using the Master Admin Key (GATEWAY_MASTER_ADMIN_KEY):

Authorization: Bearer sk-gw-master-admin-secret-key

Control Plane Groups Summary​

#GroupPrimary EndpointsCore Function
1OrganizationsPOST/GET /admin/v1/organizationsTenant org creation and budget caps
2SubscriptionsPOST/GET /admin/v1/organizations/{orgID}/subscriptionsLayer 2 provider enablement
3Model PoliciesPOST/GET /admin/v1/organizations/{orgID}/modelsLayer 3 org model overrides and token ceilings
4Guardrails & SimulatorPOST/GET /admin/v1/organizations/{orgID}/guardrails, /simulate, /guardrail-definitions, /guardrail-bindings, /tool-policies, /guardrail-usagePII/secret scanning, named registry (19 drivers, Starlark), hierarchical bindings, tool taint policies, and micro-dollar guardrail usage
5TeamsPOST/GET /admin/v1/teamsDepartmental team isolation and model scopes
6UsersPOST/GET /admin/v1/usersUser directory and role-based permissions
7Virtual API KeysPOST/GET /admin/v1/keys, POST .../revoke, DELETEScoped API key issuance and instant revocation
8Credentials VaultPOST/GET /admin/v1/credentials, /validate, .../rotateAES-256-GCM encrypted provider secrets vault
9Model Groups & DeploymentsPOST/GET /admin/v1/model-groups, /deploymentsVirtual aliases, EWMA balancers, weight matrices
10Model Catalogue & PricingGET/POST /admin/v1/catalogue, /sync, /pricingQuery and sync catalog records; manage pricing provenance
11Telemetry & Health ProbesGET /admin/v1/observability/metrics, /health/deployments, /cache/invalidateEWMA latencies, synthetic probes, cache purges
12FinOps & Audit LogsGET /admin/v1/spend/summary, /spend/logs, /audit/logsMicro-dollar accounting ledgers and governance trails

1. Organizations​

Manages enterprise tenants, baseline micro-dollar budgets, and spend reset intervals.

Create Organization (POST /admin/v1/organizations)​

curl -X POST http://localhost:8080/admin/v1/organizations \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"id": "org_acme",
"name": "Acme Corporation",
"max_budget_micros": 500000000,
"budget_reset_period": "monthly"
}'

Response (HTTP 201 Created)​

{
"id": "org_acme",
"name": "Acme Corporation",
"max_budget_micros": 500000000,
"budget_reset_period": "monthly",
"is_active": true,
"created_at": "2026-11-10T12:00:00Z"
}

List Organizations (GET /admin/v1/organizations)​

curl http://localhost:8080/admin/v1/organizations \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"data": [
{
"id": "org_acme",
"name": "Acme Corporation",
"max_budget_micros": 500000000,
"budget_reset_period": "monthly",
"is_active": true
}
]
}

2. Organization Subscriptions (Layer 2 Access Control)​

Controls which upstream cloud providers (OpenAI, Anthropic, Gemini, Mistral, Cohere) a tenant is authorized to invoke.

Configure Provider Subscription (POST /admin/v1/organizations/{orgID}/subscriptions)​

curl -X POST http://localhost:8080/admin/v1/organizations/org_acme/subscriptions \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "anthropic",
"is_enabled": true
}'

Response (HTTP 200 OK)​

{
"org_id": "org_acme",
"provider": "anthropic",
"is_enabled": true,
"updated_at": "2026-11-10T12:05:00Z"
}

Get Organization Subscriptions (GET /admin/v1/organizations/{orgID}/subscriptions)​

curl http://localhost:8080/admin/v1/organizations/org_acme/subscriptions \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"data": [
{ "provider": "anthropic", "is_enabled": true },
{ "provider": "gemini", "is_enabled": true },
{ "provider": "openai", "is_enabled": false }
]
}

3. Organization Model Policies (Layer 3 Access Control)​

Defines org-level model availability overrides and hard caps on output token generation.

Set Model Policy (POST /admin/v1/organizations/{orgID}/models)​

curl -X POST http://localhost:8080/admin/v1/organizations/org_acme/models \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"global_model_id": "anthropic/claude-sonnet-5-5",
"is_enabled": true,
"max_tokens_override": 4096
}'

Response (HTTP 200 OK)​

{
"org_id": "org_acme",
"global_model_id": "anthropic/claude-sonnet-5-5",
"is_enabled": true,
"max_tokens_override": 4096,
"updated_at": "2026-11-10T12:10:00Z"
}

List Model Policies (GET /admin/v1/organizations/{orgID}/models)​

curl http://localhost:8080/admin/v1/organizations/org_acme/models \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

4. Security Guardrails & Simulator​

Configures regex-based Personally Identifiable Information (PII) redaction, secret scanning (e.g. AWS secrets, GitHub tokens, OpenAI keys), and prompt injection filters.

Set Guardrail Policy (POST /admin/v1/organizations/{orgID}/guardrails)​

curl -X POST http://localhost:8080/admin/v1/organizations/org_acme/guardrails \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"enable_secret_detection": true,
"secret_action": "redact",
"enable_pii_detection": true,
"pii_action": "redact",
"custom_regex_patterns": ["ACME-[0-9]{6}"]
}'

Response (HTTP 200 OK)​

{
"org_id": "org_acme",
"enable_secret_detection": true,
"secret_action": "redact",
"enable_pii_detection": true,
"pii_action": "redact",
"custom_regex_patterns": ["ACME-[0-9]{6}"]
}

Retrieve Guardrail Policy (GET /admin/v1/organizations/{orgID}/guardrails)​

curl http://localhost:8080/admin/v1/organizations/org_acme/guardrails \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Stateless Guardrails Simulator (POST /admin/v1/organizations/{orgID}/guardrails/simulate)​

Tests safety rules against sample prompts without saving records or incurring upstream LLM token costs:

curl -X POST http://localhost:8080/admin/v1/organizations/org_acme/guardrails/simulate \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Here is my secret sk-proj-1234567890abcdef and SSN 000-11-2222 for ticket ACME-102938",
"policy": {
"enable_secret_detection": true,
"secret_action": "redact",
"enable_pii_detection": true,
"pii_action": "redact",
"custom_regex_patterns": ["ACME-[0-9]{6}"]
}
}'

Response (HTTP 200 OK)​

{
"allowed": true,
"applied_action": "redact",
"violations": ["secret_detected", "pii_detected", "custom_pattern_matched"],
"redacted": true,
"redacted_prompt": "Here is my secret [REDACTED_SECRET] and SSN [REDACTED_SSN] for ticket [REDACTED_CUSTOM]"
}

5. Teams​

Isolates departments or project teams within an organization, assigning dedicated budgets and model subsets.

Create Team (POST /admin/v1/teams)​

curl -X POST http://localhost:8080/admin/v1/teams \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "org_acme",
"name": "core-platform",
"max_budget_micros": 100000000,
"allowed_models": ["fast", "reasoning", "anthropic/claude-sonnet-5-5"]
}'

Response (HTTP 201 Created)​

{
"id": "team_core_plat",
"org_id": "org_acme",
"name": "core-platform",
"max_budget_micros": 100000000,
"allowed_models": ["fast", "reasoning", "anthropic/claude-sonnet-5-5"],
"created_at": "2026-11-10T12:15:00Z"
}

List Teams (GET /admin/v1/teams?org_id={orgID})​

curl "http://localhost:8080/admin/v1/teams?org_id=org_acme" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

6. Users​

Manages human developers, service accounts, and enterprise roles (admin, developer, finance_auditor).

Create User (POST /admin/v1/users)​

curl -X POST http://localhost:8080/admin/v1/users \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "org_acme",
"team_id": "team_core_plat",
"email": "engineer@acme.com",
"role": "developer"
}'

Response (HTTP 201 Created)​

{
"id": "usr_99182ab",
"org_id": "org_acme",
"team_id": "team_core_plat",
"email": "engineer@acme.com",
"role": "developer",
"created_at": "2026-11-10T12:20:00Z"
}

List Users (GET /admin/v1/users?org_id={orgID})​

curl "http://localhost:8080/admin/v1/users?org_id=org_acme" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

7. Virtual API Keys (Layer 4 Access Control)​

Issues high-entropy virtual keys (sk-gw-...) with budget caps, RPM/TPM sliding windows, and granular model allowlists.

Issue Virtual Key (POST /admin/v1/keys)​

curl -X POST http://localhost:8080/admin/v1/keys \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "org_acme",
"team_id": "team_core_plat",
"name": "orders-service-prod",
"role": "service_account",
"max_budget_micros": 50000000,
"rate_limit_rpm": 1200,
"rate_limit_tpm": 600000,
"allowed_models": ["fast", "gemini-2.5-flash"],
"allowed_mcp_servers": ["github-tools"],
"allowed_a2a_agents": ["analyst-agent"]
}'

Response (HTTP 201 Created)​

{
"id": "key_0192ab4f",
"org_id": "org_acme",
"team_id": "team_core_plat",
"name": "orders-service-prod",
"key": "sk-gw-prod-7f9a2b8c4d1e2f3a",
"key_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"max_budget_micros": 50000000,
"rate_limit_rpm": 1200,
"rate_limit_tpm": 600000,
"allowed_models": ["fast", "gemini-2.5-flash"],
"created_at": "2026-11-10T12:25:00Z"
}

[!CAUTION] The plain-text key key is returned only once at creation time. GoRoute stores only the SHA-256 digest key_hash.

List Virtual Keys (GET /admin/v1/keys?org_id={orgID})​

curl "http://localhost:8080/admin/v1/keys?org_id=org_acme" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Revoke Virtual Key (POST /admin/v1/keys/{keyID}/revoke or DELETE)​

Instantly purges key permissions from L1 in-memory caches and Redis keyspace:

curl -X POST http://localhost:8080/admin/v1/keys/key_0192ab4f/revoke \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"id": "key_0192ab4f",
"status": "revoked"
}

8. Provider Credentials Vault​

Manages upstream provider API keys encrypted at rest with AES-256-GCM. Provides live preflight validation and zero-downtime key rotation.

Create Credential (POST /admin/v1/credentials)​

curl -X POST http://localhost:8080/admin/v1/credentials \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "org_acme",
"provider": "openai",
"api_key": "sk-proj-prod-secret-api-key",
"base_url": "https://api.openai.com/v1"
}'

Response (HTTP 201 Created)​

{
"id": "cred_0198aa2b",
"org_id": "org_acme",
"provider": "openai",
"base_url": "https://api.openai.com/v1",
"is_valid": true,
"created_at": "2026-11-10T12:30:00Z"
}

List Credentials (GET /admin/v1/credentials)​

curl http://localhost:8080/admin/v1/credentials \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

[!NOTE] All returned credentials mask secrets (e.g. sk-proj-***).

Preflight Credential Validation (POST /admin/v1/credentials/validate)​

Validates raw credentials against the upstream vendor API before storing them in the vault:

curl -X POST http://localhost:8080/admin/v1/credentials/validate \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "openai",
"api_key": "sk-proj-prod-secret-api-key",
"base_url": "https://api.openai.com/v1"
}'

Response (HTTP 200 OK)​

{
"valid": true,
"validation_status": "success",
"discovered_models": 34,
"latency_ms": 118
}

Rotate Credential (POST /admin/v1/credentials/{credID}/rotate)​

Atomically updates the secret key with zero connection interruption:

curl -X POST http://localhost:8080/admin/v1/credentials/cred_0198aa2b/rotate \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"api_key": "sk-proj-new-rotated-secret-key"
}'

Validate Stored Credential (POST /admin/v1/credentials/{credID}/validate)​

Tests an already-persisted vault credential:

curl -X POST http://localhost:8080/admin/v1/credentials/cred_0198aa2b/validate \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

9. Model Groups & Deployments​

Configures logical routing groups (aliases) and physical model deployment matrices.

Create Model Group (POST /admin/v1/model-groups)​

curl -X POST http://localhost:8080/admin/v1/model-groups \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "fast",
"routing_strategy": "weighted-shuffle",
"fallback_group_ids": ["reasoning"]
}'

Response (HTTP 201 Created)​

{
"id": "mg_fast_019",
"name": "fast",
"routing_strategy": "weighted-shuffle",
"fallback_group_ids": ["reasoning"]
}

Create Deployment (POST /admin/v1/deployments)​

Adds a model deployment to a group with priority, weight, and rate limit capacities:

curl -X POST http://localhost:8080/admin/v1/deployments \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"model_group_id": "mg_fast_019",
"global_model_id": "gemini/gemini-2.5-flash",
"credential_id": "cred_gemini_vault",
"priority": 1,
"weight": 70,
"rpm_capacity": 2000,
"tpm_capacity": 2000000
}'

Response (HTTP 201 Created)​

{
"id": "dep_0192cd",
"model_group_id": "mg_fast_019",
"global_model_id": "gemini/gemini-2.5-flash",
"priority": 1,
"weight": 70,
"health_state": "CLOSED"
}

List Deployments (GET /admin/v1/deployments?model_group_id={groupID})​

curl "http://localhost:8080/admin/v1/deployments?model_group_id=mg_fast_019" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

10. Model Catalogue & Pricing Provenance​

Queries and synchronizes model catalog records and manages pricing provenance. Catalog contents can change as provider offerings and discovery settings change; a catalog entry does not by itself guarantee that a model is available to every tenant or virtual key.

Query Catalogue (GET /admin/v1/catalogue?provider={provider}&search={query})​

curl "http://localhost:8080/admin/v1/catalogue?provider=anthropic&search=claude" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Import Embedded Models (POST /admin/v1/catalogue/import?provider={provider})​

curl -X POST "http://localhost:8080/admin/v1/catalogue/import?provider=gemini" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Update Model Pricing (POST /admin/v1/catalogue/pricing)​

Promotes pricing status to "verified" with contract provenance:

curl -X POST http://localhost:8080/admin/v1/catalogue/pricing \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"global_model_id": "gemini/gemini-2.5-flash",
"input_cost_micros_per_1m": 150000,
"output_cost_micros_per_1m": 600000,
"cached_input_cost_micros_per_1m": 37500,
"pricing_status": "verified",
"pricing_provenance_source": "official-vendor-pricing-2025",
"pricing_effective_date": "2025-11-01"
}'

Pricing Revision Audit Trail (GET /admin/v1/catalogue/pricing?global_model_id={modelID})​

curl "http://localhost:8080/admin/v1/catalogue/pricing?global_model_id=gemini/gemini-2.5-flash" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

11. Telemetry, Health Probes & Cache Invalidation​

Monitors runtime latency, executes synthetic probes across deployments, and purges response or virtual key caches.

Metrics Snapshot (GET /admin/v1/observability/metrics)​

Returns real-time JSON metrics with latency percentiles and cache hit ratios:

curl http://localhost:8080/admin/v1/observability/metrics \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"total_requests": 142850,
"latency_p50_ms": 1.45,
"latency_p95_ms": 3.12,
"latency_p99_ms": 4.88,
"cache_hit_ratio": 0.428,
"active_circuit_breakers": {
"closed": 12,
"half_open": 1,
"open": 0
}
}

Deployment Health States (GET /admin/v1/health/deployments)​

curl http://localhost:8080/admin/v1/health/deployments \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Trigger Synthetic Health Probes (POST /admin/v1/health/probe)​

curl -X POST http://localhost:8080/admin/v1/health/probe \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Cache Invalidation (POST /admin/v1/cache/invalidate)​

Purges cached virtual keys or exact-match response cache keys:

curl -X POST http://localhost:8080/admin/v1/cache/invalidate \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"org_id": "org_acme",
"key_id": "key_0192ab4f"
}'

Response (HTTP 200 OK)​

{
"status": "cache_invalidated",
"purged_entries": 1
}

12. FinOps Spend & Governance Audit Logs​

Access real-time spend analytics and immutable regulatory audit logs.

Spend Summary (GET /admin/v1/spend/summary?org_id={orgID}&team_id={teamID})​

curl "http://localhost:8080/admin/v1/spend/summary?org_id=org_acme" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"org_id": "org_acme",
"total_spend_micros": 48291000,
"budget_max_micros": 500000000,
"budget_remaining_micros": 451709000,
"spend_by_model": {
"gemini/gemini-2.5-flash": 12450000,
"anthropic/claude-sonnet-5-5": 35841000
}
}

Spend Logs (GET /admin/v1/spend/logs?org_id={orgID}&limit={limit}&offset={offset})​

curl "http://localhost:8080/admin/v1/spend/logs?org_id=org_acme&limit=10" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"data": [
{
"request_id": "req_991efda4-7fab-4b03",
"trace_id": "bad98e7deea34d7c810a963d9ed2c4ef",
"model": "gemini-2.5-flash",
"provider": "gemini",
"cost_micros": 45,
"prompt_tokens": 24,
"completion_tokens": 42,
"cached_tokens": 0,
"created_at": "2026-11-10T12:40:00Z"
}
],
"total": 1
}

Governance Audit Logs (GET /admin/v1/audit/logs?org_id={orgID}&limit={limit})​

curl "http://localhost:8080/admin/v1/audit/logs?org_id=org_acme&limit=10" \
-H "Authorization: Bearer $GATEWAY_MASTER_ADMIN_KEY"

Response (HTTP 200 OK)​

{
"data": [
{
"actor_id": "admin",
"action": "virtual_key.issued",
"resource": "virtual_key",
"resource_id": "key_0192ab4f",
"details": { "name": "orders-service-prod", "rpm_limit": 1200 },
"created_at": "2026-11-10T12:25:00Z"
}
]
}

Next Steps​