Credentials

Credentials | Workloads | Policies

Credentials give the gateway access to AI provider APIs. How you manage them depends on your deployment:

Table of Contents

• Managing credentials in the console
  • How the console manages policy rules
  • AWS Bedrock: two credential types
• [Managing credentials on the Free Gateway](#managing-credentials-on-the-Free Gateway)
  • File structure
  • Field reference
  • provider valid values
  • mode valid values
  • billing_owner valid values
  • How secrets are resolved
  • Pushing credentials at runtime
  • Trust model: alias vs inline
  • Fail-fast on missing credential secret
• Related Topics

Managing credentials in the console

Go to Credentials in the left nav. From there you can:

• Add a credential: select the provider, enter a name, and paste your API key
• View credentials: see provider, mode, and billing owner for each entry
• Delete a credential: removes the credential and its associated policy rules

The console stores credentials securely and distributes them to your gateway automatically. No YAML files needed.

How the console manages policy rules

When you add a credential in the console, the Control Plane (CP) automatically generates policy rules that allow traffic to that provider; you do not need to configure policies manually for basic access. When you delete a credential, those rules are removed and traffic to that provider is denied.

AWS Bedrock: two credential types

AWS Bedrock accepts two different credential shapes, and the console's Add Credential form asks which one you're using before showing the matching fields:

The console preselects Bedrock API key: it's the one-field path, and the one most users already hold after following AWS's current getting-started docs. AWS recommends access key + SigV4 for production workloads; long-term API keys are intended for exploration and development. The form shows this recommendation inline when API key mode is selected.

Region is required in both modes; Bedrock's runtime endpoint is bedrock-runtime.<region>.amazonaws.com regardless of credential type.

Internally, both shapes are encoded as JSON inside the credential's secret_ref, discriminated by an auth_type field:

// Bedrock API key
{"auth_type": "api_key", "api_key": "…", "region": "us-east-1"}

// Access key + secret (SigV4)
{"auth_type": "sigv4", "access_key_id": "AKIA…", "secret_access_key": "…", "region": "us-east-1"}

A credential created before this distinction existed has no auth_type field. The gateway infers sigv4 for those, since that was the only shape available at the time; no migration is needed for existing Bedrock credentials.

Managing credentials on the Free Gateway

Location: configs/credentials/credentials.yaml (env: MVGC_CREDENTIALS_DIR)

The credentials file registers AI provider API keys for free (self-hosted) gateway deployments.

File structure

credentials:
  - credential_id: cred-openai
    provider: openai
    mode: alias
    billing_owner: customer
    secret_ref: OPENAI_API_KEY
    created_at: "2026-03-15T00:00:00Z"
    updated_at: "2026-03-15T00:00:00Z"

Field reference

credential_id vs secret_ref: credential_id is a logical name used in policy rules and API calls. secret_ref is the name of the environment variable the gateway reads to obtain the actual API key. There is no automatic derivation between them. For example, a credential with credential_id: cred-openai and secret_ref: OPENAI_API_KEY means policy rules reference it as cred-openai, while the gateway resolves the secret by calling os.Getenv("OPENAI_API_KEY"). You can name either field however you like, as long as they are consistent within your deployment.

provider valid values

Each provider maps 1:1 to a dedicated connector with provider-specific logic for auth headers, token counting, and streaming. The connector_id field in policy effects and the provider field on credentials use the same values today. In a future release these may diverge -- for example, to support multiple connector versions for a single provider, or a single connector that serves multiple providers.

mode valid values

brokered and attested modes are reserved for future use.

billing_owner valid values

How secrets are resolved

For alias mode the gateway reads the named environment variable at request time. The recommended way to supply these is via the env: section of mvgc.yaml: values there are injected into the process environment at startup and never override variables already set by the shell or service manager:

# mvgc.yaml
env:
  OPENAI_API_KEY: "sk-..."
  ANTHROPIC_API_KEY: "sk-ant-..."
  GEMINI_API_KEY: "AIza..."
  AZURE_OPENAI_API_KEY: "..."
  COHERE_API_KEY: "..."

Alternatively, set them directly in the process environment (shell export, systemd EnvironmentFile, or Docker Compose .env). Direct process env vars always take precedence over the env: section.

For inline mode, set secret_ref to the literal API key in credentials.yaml and omit the environment variable. Treat credentials.yaml as a sensitive file (same as .env) when using this mode.

credentials:
  - credential_id: cred-openai-inline
    provider: openai
    mode: inline
    billing_owner: customer
    secret_ref: "sk-your-openai-api-key-here"

Pushing credentials at runtime

Register a credential

curl -X PUT http://localhost:7080/v1/admin/credentials \
  -H "MVGC-Admin-Token: $MVGC_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "cred-openai",
    "provider": "openai",
    "mode": "alias",
    "billing_owner": "customer",
    "secret_ref": "OPENAI_API_KEY"
  }'

Reload all credentials from file

If you edit credentials.yaml on disk after the gateway is already running, use this endpoint to apply the file contents without a restart. All credentials in the file are upserted (overwriting any current DB values):

curl -s -X POST http://localhost:7080/v1/admin/credentials/reload \
  -H "MVGC-Admin-Token: $MVGC_ADMIN_TOKEN" | jq .

The gateway reads every *.yaml file from MVGC_CREDENTIALS_DIR and upserts each entry.

Trust model: alias vs inline

Choosing a credential mode is a trust model decision:

Reserve inline for managed gateways. For self-hosted deployments, alias keeps secrets off the control plane entirely.

Fail-fast on missing credential secret

When policy allows a request but the target is a known AI provider and no credential secret can be resolved (empty env var, missing alias, no matching credential), the gateway returns HTTP 403 with an actionable message rather than forwarding the request unauthenticated. This prevents opaque upstream 401 errors and makes misconfigured credentials immediately visible.

Related Topics

• Policies — credential selection in policy rules