Governed Providers

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Provider calls route through the runtime provider transport. The transport uses the control-plane admission decision, commits usage from provider-reported tokens, and records route/evidence metadata without exposing provider secrets.

Use governed providers when model traffic must honor approved provider routes, regional residency, provider account rotation, TPM/cost controls, and release approval evidence. A workload should not call model providers directly from an ungoverned plugin when the same call can be represented as a release-bound model_policy.

If outbound response filtering blocks a provider response after the provider has returned, runtime-gateway commits burned usage instead of releasing the reservation. This keeps TPM and cost accounting aligned with provider-side spend.

Provider Route Fields

The provider route is embedded in a model_policy asset version.

Runtime Flow

llm_call or agent step
  -> resolve release-bound model_policy
  -> request provider admission
  -> reserve TPM/cost budget
  -> call provider through governed transport
  -> commit provider-reported usage
  -> record evidence and bounded route metadata

Provider secrets are resolved through release connection bindings and secrets, not embedded in the model policy content.

Credential Verification

When a Provider is saved with a credential reference, the control plane performs a bounded, point-in-time verification and returns a closed status/reason pair. The raw credential and provider response body are never returned or persisted. OpenRouter verification uses its small /api/v1/key identity endpoint; its larger /api/v1/models catalogue remains the separate model-discovery path. Discovery therefore does not need to fit inside the credential-verification response limit.

verified has a null reason. invalid means the provider rejected the credential or the referenced Secret is definitively missing. unverified means the check could not establish a verdict, including provider unavailability, timeout, redirect, malformed response, or a response exceeding the shared 64 KiB verification boundary. A failed verification is informational and does not roll back a valid Provider write; operators should correct the credential or endpoint and save again.

Provider Reconciliation

Provider configuration changes commit desired state first. The bounded control-plane-worker then mirrors the scoped credential, verifies the Vault generation, and reconciles Provider-owned LiteLLM deployments. It is the only control-plane process with LiteLLM route-admin or Provider-attestor access; runtime-gateway keeps the separate completion path.

Discovering provider models

Namespace administrators can use Connect → Models → Providers → Discover models after configuring a provider. Providers with a compatible, allowlisted model listing API return their canonical model identifiers and available metadata. Selecting a result materializes the namespace catalog entry and queues its deployment; pricing and reconciliation remain explicit readiness gates.

If a provider has no supported listing API, is unavailable, or returns an invalid response, the control plane reports the bounded reason and leaves the manual-entry form available. Manual identifiers are never treated as active until the normal pricing, policy, credential, and reconciliation gates pass.

Only namespace administrators can discover or materialize models for their namespace. The provider endpoint and credential remain server-owned and are never accepted from the discovery response.

Confirming cross-provider model identity

Catalog entries from different providers remain separate until a namespace administrator explicitly confirms that they represent the same model. Similar names and discovery metadata do not create a grouping. Create a stable identity, then confirm each alias using its current confirmation revision:

orqestractl model identity create \
  --namespace-id "$NAMESPACE_ID" \
  --display-name "Example model family" \
  --reason "Confirmed against the provider model documentation"
 
orqestractl model identity confirm openai gpt-x \
  --namespace-id "$NAMESPACE_ID" \
  --identity-id "$IDENTITY_ID" \
  --expected-revision 0 \
  --reason "Confirmed against the provider model documentation"

Use orqestractl --format json model list --workspace "$WORKSPACE_ID" to read the identity_id and confirmation_revision returned for each catalog alias. An alias that has never been confirmed has identity_id: null and revision 0, so it stays in its own bucket. A cleared alias also has a null identity, but retains its incremented positive revision. To replace or clear an assignment, pass the current revision with the next confirmation; a stale revision is rejected. Clearing uses --clear in place of --identity-id. Updating a catalog entry does not change its identity confirmation, and deleting then recreating an alias starts unmapped.

Use the operator API or CLI to request a replay-safe recovery pass:

orqestractl provider reconcile <namespace-id> <provider-slug> \
  --idempotency-key provider-reconcile-2026-08-14
orqestractl provider deployments <namespace-id> <provider-slug>

The reconcile response is a bounded pending projection. Deployment reads report only state, reason, desired revision, and reconciled revision; they never return provider credentials, LiteLLM response bodies, or exception text.

Operational Checks

• Provider routes must be configured through the governed provider plane.
• Provider errors and evidence artifacts must redact credential-shaped values.
• Egress-blocked provider responses still consume budget when usage exists.
• Retiring a provider account requires a dependency report before revocation.
• Route changes should be reviewed like release-impacting policy changes.

Supplier claims

Supplier claims are bounded, workspace-scoped readiness records. They do not make a customer compliance or certification assertion. An operator proposes a requirement revision containing every applicable obligation/responsibility pair and its jurisdiction and scope; a different authorized human reviews that revision. A claim proposal pins the reviewed requirement revision, current assurance generation, workload and release role, and finite validity. The control plane supplies the current release-bound deployment identity and digest. It does not accept those values or a claim outcome from the caller.

A separate authorized human reviews each applicable pair as supported or gap and links evidence. The current view derives satisfied, gap, or unavailable with bounded reasons per pair. Byte integrity and freshness alone do not establish semantic support. Pair outcome keys join the opaque obligation and responsibility references with /, which is outside the reference alphabet. Historical claim rows retain supported, gap, and unreviewed pair decisions with closed reasons. They are decision history only and do not show whether a claim is currently valid. Stale generation or requirement bindings, expired evidence, changed owner, missing review, or unresolved trusted state cannot remain satisfied. History is paginated and excludes evidence bytes, private assertions, secrets, URLs, and credential hashes.

The supplier-assurance operator page and orqestractl ict-provider-risk assurance commands provide this workflow. SDK callers can use client.ict_provider_risks proposal, current, and history methods. MCP tools can read and propose; agent tools cannot review requirements or semantic pairs.

Supplier claim CLI

Use the existing assurance command group to review or propose supplier claims:

orqestractl ict-provider-risk assurance requirements current <provider-risk-id>
orqestractl ict-provider-risk assurance requirements history <provider-risk-id> --limit 50
orqestractl ict-provider-risk assurance requirements propose <provider-risk-id> \
  --expected-revision 2 \
  --requirement-pair '{"obligation_ref":"obligation:retention","responsibility_ref":"owner:platform","jurisdiction":"EU","scope":"model:chat","applicable":true}' \
  --mapping-pair '{"obligation_ref":"obligation:retention","responsibility_ref":"owner:platform","jurisdiction":"EU","scope":"model:chat"}'
orqestractl ict-provider-risk assurance requirements review <provider-risk-id> 3
orqestractl ict-provider-risk assurance claim current <provider-risk-id>
orqestractl ict-provider-risk assurance claim history <provider-risk-id> --limit 50

Use assurance claim propose with the reviewed requirement revision, current assurance generation, workload, environment, release role, claim generation, and finite --valid-until. assurance claim review accepts one --decision JSON object per applicable pair. Run review commands only as an authorized human CLI identity; agent tools cannot perform human reviews. A 409 means a pinned revision or generation changed; refresh current state before proposing again. Repeating an identical claim does not extend its validity.

Declarative supplier proposals

The orqestractl sync command accepts supplier requirement and claim proposals in a package manifest. These sections submit proposals only: they cannot approve requirements, record claim outcomes, or select trusted deployment identity. Keep revision counters and valid_until explicit in version control; sync does not refresh counters or extend validity on a retry. Read history through the claim history command.

Propose a requirement revision in orqestra.package.yaml:

api_version: orqestra.ai/v1alpha1
kind: DeclarativePackage
supplier_requirement_proposals:
  - provider_risk_id: 00000000-0000-4000-8000-000000000101
    expected_revision: 0
    requirement_pairs:
      - obligation_ref: obligation:retention
        responsibility_ref: owner:platform
        jurisdiction: EU
        scope: model:chat
        applicable: true
    mapping_pairs:
      - obligation_ref: obligation:retention
        responsibility_ref: owner:platform
        jurisdiction: EU
        scope: model:chat

Run orqestractl sync preview --dir . --workspace "$WORKSPACE_ID" and then orqestractl sync apply --dir . --workspace "$WORKSPACE_ID". An authorized human reviews the resulting revision separately:

orqestractl ict-provider-risk assurance requirements current "$PROVIDER_RISK_ID"
orqestractl ict-provider-risk assurance requirements review "$PROVIDER_RISK_ID" 1

Only after the current requirement revision is reviewed and the assurance generation is verified should a claim manifest be applied:

api_version: orqestra.ai/v1alpha1
kind: DeclarativePackage
supplier_claim_proposals:
  - provider_risk_id: 00000000-0000-4000-8000-000000000101
    expected_requirement_revision: 1
    expected_assurance_generation: 3
    expected_claim_generation: 0
    workload_id: 00000000-0000-4000-8000-000000000202
    environment: production
    role: model_policy
    valid_until: "2027-01-01T00:00:00Z"

Claim review remains a separate human action. Inspect the server-derived current claim and use orqestractl ict-provider-risk assurance claim review to record pair-level semantic decisions. A proposal does not establish a compliance or certification outcome.

Inspecting Provider Dependencies

Operators with release.view on a workspace can inspect which workloads and releases depend on each governed provider route. This is the same data behind release diffs and policy review — surfaced as a flat list so you can answer “what breaks if I retire this provider account?” without opening every release.

The API is workspace-scoped:

GET /v1/provider-governance/dependencies?workspace_id={ws}
       [&provider=…&model=…&route_id=…&account_ref=…&region=…]

Each row identifies a workload/release/asset_version triple plus the provider, model, route_id, account_ref, region, residency, and any declared fallback_route_ids. Rows also include the route’s compliance posture, lifecycle lane, effective provider-posture hierarchy, and provider-policy advisories or denials recorded during activation. Filters narrow the result without changing authorization.

Portal

The Connect → Models → Provider health page lists every dependency in the active workspace. Use the provider and region filter chips to focus the inventory; the search box matches workload slug, provider, model, route, and account reference. Release state is rendered with the same tone scale as the release queue. Compliance and posture columns show the attestation level, lifecycle lane, winning scope, contributing scopes, rejected candidates, and provider-policy advisory or denial basis.

CLI

orqestractl provider dependencies \
  --provider azure_openai \
  --region westeurope

The command renders a tabular view with workload_slug, release_state, provider, model, route_id, account_ref, region, compliance designations, claim level, lifecycle lane, effective posture scope, contributing scopes, rejected posture candidates, and advisory/denial basis. Use the global --format json flag for scripted consumption. The command returns the complete inventory by default (paging through every server-side page); pass --limit/--offset to fetch a single bounded page instead.

SDK

The endpoint is paginated. For blast-radius and rotation workflows that must see every affected workload, use list_all(), which pages through the full inventory:

async with OrqestraClient(...) as client:
    deps = await client.provider_dependencies.list_all(
        provider="azure_openai",
        region="westeurope",
    )

Use list(..., limit=..., offset=...) when you want a single bounded page (at most 200 rows) instead of the complete inventory.

AI Dev Kit (MCP)

The MCP server exposes list_provider_dependencies so an assistant can answer provider/route impact questions without leaving the chat. The tool accepts the same filters as the CLI/SDK plus an optional workspace_id, and returns the same rows, including posture hierarchy and provider-policy advisories. By default it returns the complete inventory (paging through every page) so blast-radius checks never miss a workload; pass limit/offset for a single bounded page. Use it before approving a release or rotating a provider account to map the blast radius.

Rotation Workflow

1. List dependencies for the provider account or route you plan to rotate.
2. Identify active releases using that route.
3. Create or approve a replacement provider route and connection.
4. Create new approved model_policy asset versions that point to the replacement.
5. Bind those versions into draft releases and run validation gates.
6. Promote the releases through the normal approval path.
7. Re-run dependency reporting to confirm no active release depends on the old route.
8. Revoke or disable the old provider account only after the dependency report is empty.

Failure Modes