> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airmux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider credentials

> Store upstream API keys at instance, organization, or workspace scope and control which requests may use them.

Provider credentials are upstream API keys that `airmux` uses after an inference request has been authenticated and
routed. They are separate from inference keys and management keys.

## Credential scopes

| Scope        | Available to                                                     |
| ------------ | ---------------------------------------------------------------- |
| Instance     | Every organization unless policy excludes `platform` credentials |
| Organization | Every workspace in one organization                              |
| Workspace    | One workspace                                                    |

The data plane receives only a versioned secret reference in its configuration bundle. The secret value stays in the
configured secret store and is resolved only for the selected request.

## Add a credential

The webapp exposes credentials at instance, organization, and workspace settings. The CLI creates organization or workspace credentials:

```bash theme={null}
printf '%s' "$OPENAI_API_KEY" | airmux provider-credentials add openai --name production --priority 10
```

Add `--org` to share the credential across the active organization. Without it, the credential belongs to the selected workspace.

```bash theme={null}
airmux provider-credentials list
airmux provider-credentials list --org
```

Values are never returned. Lists show metadata, the last four characters, current version, enabled state, and observed health.

## Rotate, disable, or delete

```bash theme={null}
printf '%s' "$OPENAI_API_KEY_NEXT" | airmux provider-credentials rotate "$CREDENTIAL_ID"
airmux provider-credentials disable "$CREDENTIAL_ID"
airmux provider-credentials disable "$CREDENTIAL_ID" --enable
airmux provider-credentials rm "$CREDENTIAL_ID"
```

Rotation increments the credential version. When the next bundle arrives, the versioned cache key changes, so gateways
fetch the new value without waiting for the old cache entry to expire.

## Selection and health

Within the selected scope, lower priority values are tried first. Credential status is advisory and reflects the latest
ingested request event: `unknown`, `live`, `invalid`, or `rate_limited`. Request-time selection also uses an in-memory
cooldown after a rate limit.

Use a `credential_access` rule to allow only selected scopes. Multiple matching credential rules intersect, so every
rule must allow a scope for it to remain eligible.

## Secret stores

The default managed deployment uses a file-backed store on the persistent `/state` volume. Standalone mode uses
environment variables and can resolve only one value per provider, making it appropriate for local or single-tenant use.
Both planes must point at the same store when deployed separately.

<Warning>
  Back up and restore the database and secret store together. Database metadata without the corresponding secret values
  leaves credentials that cannot resolve.
</Warning>