# Model and credential providers

Interceptor authenticates the target agent's model and embedding requests on the
host. The application uses its native API through the sandbox's model proxy, with
synthetic SDK credentials when required. Real provider credentials never enter
the target container. Operator configures Attack Harness model access separately.

## Choose a model provider

Select `--model-provider` to match the API used by your application. Interceptor
does not translate one model API into another. Point the application's SDK at the
local proxy and configure its upstream provider independently on the host.

| `--model-provider` | Application API | Host `--provider-base-url` |
| --- | --- | --- |
| `openai-chat` | OpenAI Chat Completions | `https://api.openai.com/v1` |
| `openai-responses` | OpenAI Responses | `https://api.openai.com/v1` |
| `anthropic-messages` | Anthropic Messages | `https://api.anthropic.com`; also set `--provider-api-version` to the required API header value. |
| `gemini-api` | Gemini generateContent | `https://generativelanguage.googleapis.com/v1beta` |
| `vertex-gemini` | Gemini generateContent | `https://YOUR_LOCATION-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/YOUR_LOCATION`, ending before `publishers/google/models`. |
| `azure-openai` | OpenAI Chat or Responses | `https://YOUR_RESOURCE.openai.azure.com/openai/v1` |
| `litellm` | OpenAI Chat or Responses | Your gateway's base URL, such as `https://YOUR_GATEWAY/v1`. |
| `bedrock-converse` | Bedrock Converse | Omit HTTP endpoint/key options; use `--aws-region` and host AWS authentication. |

These are **base URLs**, unlike Operator's complete operation URLs. Repeat
`--allow-model` for each exact model identifier the agent may request. For Azure,
use deployment names; for Bedrock, use the applicable model or inference-profile
identifier. The application cannot choose the upstream server.

The proxy supports non-streaming native requests. Streaming, multimodal/file
inputs, provider-hosted tools, and background operations are outside its supported
subset. A Responses client must send explicit input rather than depend on
provider-stored conversation state. Choose an API and model supported by the
application; selecting a different provider alone does not adapt its SDK.

## Configure generation

This command connects an OpenAI Chat application to a stored model key. Replace
the paths and `YOUR_MODEL`; prepare the [credential file](#configure-credential-providers)
first:

```sh
interceptor run --environment ./interceptor-environment \
  --production \
  --model-provider openai-chat \
  --provider-base-url https://api.openai.com/v1 \
  --provider-auth secret-store \
  --credential-config /absolute/private/credentials.yaml \
  --model-credential-id model-key \
  --allow-model YOUR_MODEL
```

Configure the OpenAI application SDK with base URL
`http://127.0.0.1:18080/v1`. For Anthropic, use the proxy origin with the SDK's
normal `/v1/messages` route; for Gemini, use its corresponding local generateContent
route. For Bedrock, use `http://127.0.0.1:18080` as the Bedrock Runtime endpoint.
Use application-specific configuration or an invocation adapter; there is no
universal SDK environment variable.

Declare any SDK-required synthetic key in the blueprint's launch environment and
its `credentials` entries with `accepted_by: model-proxy`. The
[customer-support recipe](https://docs.intrusive.ai/pages/guides/customer-support-environment.html)
shows this for OpenAI-compatible generation and embeddings. Interceptor replaces
synthetic authentication with real authentication only on the host.

## Select model authentication

Choose one route-appropriate `--provider-auth` mode. Store authentication is
configured independently in the credential file.

| `--provider-auth` | Model providers | Additional options or host configuration |
| --- | --- | --- |
| `secret-store` or `api-key` | All HTTP providers above | `--credential-config FILE --model-credential-id ID`. |
| `api-key-env` | All HTTP providers above | `--model-api-key-env NAME`; omit stored-credential options. The host variable contains the key. |
| `workload-token` | Anthropic | Use `--credential-config FILE --model-credential-id ID` for a bearer token. The administrator handles renewal. |
| `workload-identity` | Bedrock, Azure OpenAI, Vertex | Configured cloud workload identity; omit stored-key and environment-key options. |
| `aws-profile` | Bedrock | `--aws-profile NAME --aws-region REGION`. |
| `aws-environment` | Bedrock | Host AWS access-key pair and optional session token; use `--aws-region REGION`. |
| `google-adc` | Vertex | Explicit Google Application Default Credentials. |
| `azure-cli` | Azure OpenAI | Existing Azure CLI login available to the process. |
| `azure-client-secret` | Azure OpenAI | Host Azure tenant, client, and client-secret variables. |
| `none` | LiteLLM | Intentionally unauthenticated gateway; omit all credential options. |

Explicit environment-key selection also works with `--production`; implicit
environment-key fallback does not. Choose a mode explicitly so local development
and automation use the same credential source. Do not combine identity modes with
stored-key options. For example, Bedrock with an existing named AWS profile uses:

```sh
interceptor run --environment ./interceptor-environment \
  --production \
  --model-provider bedrock-converse \
  --provider-auth aws-profile \
  --aws-profile YOUR_AWS_PROFILE \
  --aws-region us-east-1 \
  --allow-model YOUR_BEDROCK_MODEL_OR_INFERENCE_PROFILE
```

For Vertex or Azure identity access, use the matching base URL from the provider
table, select `google-adc`, `azure-cli`, or the applicable workload mode, and omit
the key options. See [host identity setup](#configure-host-identities).

## Configure embeddings independently

Generation configuration does not enable embeddings or supply their credentials.
Add the relevant option group to your complete `interceptor run` command.

For OpenAI-compatible embeddings with a stored API key:

```sh
--embeddings-provider openai-compatible \
--embeddings-base-url https://api.openai.com/v1 \
--embeddings-auth secret-store \
--embeddings-credential-config /absolute/private/credentials.yaml \
--embeddings-credential-id model-key \
--allow-embedding-model text-embedding-3-large
```

This explicitly reuses `model-key`; use a separate credential ID or file when
appropriate. Alternatives are `--embeddings-auth api-key-env` with
`--embeddings-api-key-env NAME`, or `--embeddings-auth none` for an intentionally
unauthenticated gateway. Omit stored-credential options for those alternatives.
The application uses the proxy's `/v1/embeddings` route with a synthetic key.

For native Amazon Titan text embeddings:

```sh
--embeddings-provider bedrock-titan \
--embeddings-auth aws-profile \
--embeddings-aws-profile YOUR_AWS_PROFILE \
--embeddings-aws-region us-east-1 \
--allow-embedding-model amazon.titan-embed-text-v2:0
```

Titan also accepts `workload-identity` or `aws-environment`; omit the profile option
for those modes. Do not supply HTTP endpoint or API-key options. Its AWS region and
profile are independent of generation. Configure the application's native Bedrock
Runtime client to use the proxy origin and declared synthetic AWS SDK credentials.

Repeat `--allow-embedding-model` for exact permitted identifiers on the compatible
route; the Titan route accepts the model shown above. Match the corpus and query
embedding model, dimensions, and normalization. Re-embed the corpus when changing
incompatible settings; equal vector dimensions do not establish compatibility.
The Quick start's support-agent recipe uses OpenAI-compatible embeddings and needs
corresponding application changes before switching to another embedding API.

## Configure credential providers

Interceptor supports AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager,
HashiCorp Vault KV v2, and 1Password. A **profile** selects a store and its permitted
secret locations; a **credential reference** gives a stored value a stable ID used
by `--model-credential-id` or `--embeddings-credential-id`. The model provider and
secret store can be in different clouds.

Create `/absolute/private/credentials.yaml` with the following structure. This
example reads a plain-text API key from AWS Secrets Manager through an explicit
host AWS profile. Replace the region, profile name, and secret location:

```yaml
profiles:
  - api_version: interceptor.dev/secret-store-profile/v1alpha1
    kind: SecretStoreProfile
    id: model-secrets
    backend_kind: aws-secrets-manager
    authentication: aws-profile
    aws_profile: YOUR_AWS_PROFILE
    region: us-east-1
    allowed_locator_prefixes: [aws://us-east-1/simulation/model-key]
    timeout_seconds: 10
    max_value_bytes: 65536
    max_cache_ttl_seconds: 300
credentials:
  - api_version: interceptor.dev/host-credential-ref/v1alpha1
    kind: HostCredentialRef
    credential_id: model-key
    store_profile_id: model-secrets
    locator:
      backend_kind: aws-secrets-manager
      region: us-east-1
      secret_id: simulation/model-key
      version_stage: AWSCURRENT
    value: {format: utf8}
    cache_ttl_seconds: 30
```

This file contains references, never the API key itself. Protect it with mode `0600`;
use regular files owned by the execution account or root, without symlinks. Use YAML
or JSON with the same structure. Both products accept either the
`operator.dev` or `interceptor.dev` credential schema namespace, so a private file
can be shared when the host accounts have the required access.

### Backend fields and secret locations

To select another backend, retain the common schema, kind, IDs, limits, and value
selection above. Replace `backend_kind` in both the profile and locator, remove
fields belonging to the previous backend, and supply these fields:

| Backend | Profile fields | `locator` fields | Example allowed prefix |
| --- | --- | --- | --- |
| `aws-secrets-manager` | `region`; `authentication`: `workload-identity`, `aws-profile`, or `aws-environment`; `aws_profile` only for named-profile access. | Matching `region`, `secret_id`; optional `version_id` or `version_stage`. | `aws://us-east-1/simulation/` |
| `azure-key-vault` | HTTPS `vault_url`; `authentication`: `workload-identity`, `azure-cli`, or `azure-client-secret`. | Matching `vault_url`, `secret_name`; optional `version`. | `https://YOUR_VAULT.vault.azure.net/secrets/simulation-` |
| `gcp-secret-manager` | `authentication`: `workload-identity` or `google-adc`. | `project`, `secret_name`, `version` such as `latest`. | `gcp://projects/YOUR_PROJECT/secrets/simulation-` |
| `hashicorp-vault` | HTTPS `vault_url`; exactly one of `vault_token_file` or `vault_proxy: true`; optional `vault_namespace`, `vault_ca_certificate`. | `mount`, `path`; optional `version` as a positive integer encoded as a string. | `vault://secret/simulation/` |
| `onepassword` | `authentication`: `onepassword-desktop` with `onepassword_account`, or `onepassword-service-account` without the account field. | `secret_reference`: `op://vault/item/[section/]field`. | `op://simulation/` |

Cloud-store authentication defaults to workload identity, except that an explicit
`aws_profile` selects that profile when `authentication` is omitted. The locator
must match the backend and the configured AWS region or Azure vault. Allowlist
prefixes restrict selection; they do not grant access at the remote store.

For example, these are the replacement profile fields and locator for Google
Secret Manager, merged into the same two records above:

```yaml
# Fields in profiles[0]; remove region and aws_profile.
backend_kind: gcp-secret-manager
authentication: google-adc
allowed_locator_prefixes: [gcp://projects/YOUR_PROJECT/secrets/simulation-]
```

```yaml
# Replace credentials[0].locator.
backend_kind: gcp-secret-manager
project: YOUR_PROJECT
secret_name: simulation-model-key
version: latest
```

### Values, caching, and store access

Use `value: {format: utf8}` when the selected secret is the key itself. For a JSON
secret, select one top-level string with
`value: {format: json-string-field, field: api_key}`. Vault KV v2 requires this
explicit field selection. Binary values, empty keys, NUL, and line breaks in the
selected credential are rejected. The resolver reads secrets; it does not create,
rotate, list, or delete them.

`timeout_seconds` defaults to 10 and permits 1–60. `max_value_bytes` defaults to
65536 and permits at most 1048576. `max_cache_ttl_seconds` defaults to 300 and permits
up to 3600. A reference's `cache_ttl_seconds` defaults to zero (no caching) and cannot
exceed its profile's ceiling. A failed refresh does not fall back to a stale value.

Grant the chosen host identity only the access it needs:

| Store | Access and setup |
| --- | --- |
| AWS Secrets Manager | `secretsmanager:GetSecretValue` on the secret; customer-managed encryption keys may also require `kms:Decrypt` and an allowing key policy. |
| Azure Key Vault | Key Vault Secrets User, or secret Get under legacy access policies. Key Vault Reader alone cannot read values. |
| Google Secret Manager | Secret Manager Secret Accessor on the selected secret, an enabled Secret Manager API, and an enabled secret version. |
| Vault KV v2 | Read access to `MOUNT/data/PATH` through an already authenticated Agent or Proxy. |
| 1Password | Read access to the selected vault/item for the desktop account or service account. |

For Vault, `vault_token_file` names an absolute private token-sink file; it is reread
on uncached resolution. Alternatively, use an authenticating Proxy with
`vault_proxy: true`. The product does not perform Vault login. Keep TLS verification
enabled; `vault_ca_certificate` supplies a trusted certificate file when needed.

For 1Password desktop access, run as the signed-in desktop user, enable
**Settings → Developer → Integrate with 1Password SDKs**, and set
`onepassword_account` to the account name or UUID. For automation, select
`onepassword-service-account` and supply `OP_SERVICE_ACCOUNT_TOKEN` only to the host
process. No `op` CLI is required. References select one field; names or IDs are
accepted, and allowed prefixes must end on a component boundary with `/`.

## Configure host identities

Run authentication setup as the account that will execute Interceptor. Model access
and permission to read a secret are separate grants.

| Selection | Host prerequisites |
| --- | --- |
| AWS `workload-identity` | Web-identity token file and role, container role, or instance role. Shared AWS files are excluded. |
| AWS `aws-profile` | Explicit profile name; for SSO, run `aws sso login --profile YOUR_AWS_PROFILE`. |
| AWS `aws-environment` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and optionally `AWS_SESSION_TOKEN` in the host process. Shared profiles are ignored. |
| Azure `workload-identity` | Federated token file with `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`, or managed identity. |
| Azure `azure-cli` | Existing `az login` session and `az` available on the process PATH. |
| Azure `azure-client-secret` | Host `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`. |
| Google `workload-identity` | Attached identity or external-account federation, including a configured `GOOGLE_APPLICATION_CREDENTIALS` file. |
| Google `google-adc` | Explicit Application Default Credentials; local setup uses `gcloud auth application-default login`, separately from `gcloud auth login`. |

AWS workload and named-profile modes reject static AWS credential environment
variables; choose `aws-environment` when using an exported access-key session.
For direct model access, grant Bedrock `InvokeModel`, Azure Cognitive Services
OpenAI User, or Vertex AI User/inference permission for the selected resource.
Google quota-project use can also require Service Usage Consumer.

In CI, AWS credential actions that export temporary keys use `aws-environment`;
Azure CLI login uses `azure-cli`; Google's federated credential file uses
`workload-identity` or `google-adc`. Keep the authenticated environment and files
available for the process lifetime. A detached service needs its own configured
account and environment and does not automatically inherit a terminal login.

## Check credential access and model routing

A credential read can be checked separately from starting a sandbox or making a
model call. With the host identity configured, use a new output path:

```sh
interceptor credentials check --live \
  --credential-config /absolute/private/credentials.yaml \
  --credential-id model-key \
  --probe-id model-key-read \
  --output /absolute/private/model-key-read.jsonl \
  --timeout-seconds 30
```

This performs a real read from the selected store. Output records the result
without the secret value. It does not prove model access. To check model routing,
start the prepared target, perform a legitimate application operation, and inspect
its output and model/embedding evidence as described in [sessions and evidence](sessions-and-evidence.md).

Check failures against the chosen account, credential ID, allowed locator prefixes,
store permissions, and model permissions. A generation credential does not enable
embedding access. Stored-credential resolution writes a private host audit record;
configuration and values are not included in public exports or blueprints.

Upstream references provide more detail on [model routing](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/model-providers.md)
and [credential stores](https://github.com/intrusiveai/interceptor_sandbox/blob/v0.1.5/docs/credential-stores.md);
choose the source tag matching your installed release.
