# Provider credentials

> Add LLM, web search, and integration credentials in Botyard, how they are stored, and how they are injected into outbound provider calls at request time.

Canonical URL: https://docs.botyard.io/docs/provider-credentials

Provider credentials are API keys, OAuth tokens, and integration records that Botyard uses
when a bot calls an external provider. They cover LLM providers, web search providers, and
integrations such as GitHub.

The important design rule is simple: bots do not receive long-lived provider keys as
environment variables. Botyard resolves the right credential at request time and injects it
only into the outbound provider call.

## Add a credential in the UI

1. Sign in to [app.botyard.io](https://app.botyard.io).
2. Open the tab that matches the credential:
   * **User menu** › **Settings** › **Credentials** › **LLM Providers** for OpenAI, Anthropic, OpenRouter, Snowflake Cortex, or compatible APIs.
   * **User menu** › **Settings** › **Credentials** › **Web Search** for search providers.
   * **User menu** › **Settings** › **Credentials** › **Integrations** for external services such as GitHub.
3. Click **Add provider**.
4. Pick a provider, enter the required fields, and save.

For API-key providers, Botyard may run a connectivity test after saving. The UI keeps only a
safe key prefix for recognition. Secret values are not returned by the API after creation.

## Credential types

Each tab on the Credentials page holds one kind of credential:

| Tab                   | What it holds                                                                      |
| --------------------- | ---------------------------------------------------------------------------------- |
| **LLM Providers**     | Language model providers. See [LLM providers](#llm-providers).                     |
| **Web Search**        | The Brave Search API.                                                              |
| **Integrations**      | External services: GitHub, Dinero, Shopify, Avola Flow, Reddit Ads, and e-conomic. |
| **Runtime Vault**     | Values your bots request on demand. See [Runtime Vault](/docs/runtime-vault).      |
| **External Channels** | Microsoft Teams or Slack links. Shown only where enabled.                          |

### LLM providers

Botyard manages the provider list, so the picker is the authoritative list. At the time of
writing it offers:

| Provider                             | Sign-in                                 |
| ------------------------------------ | --------------------------------------- |
| OpenAI API                           | API key                                 |
| Anthropic API                        | API key                                 |
| OpenRouter                           | API key                                 |
| Google AI Studio                     | API key                                 |
| Azure OpenAI / Foundry               | API key                                 |
| Snowflake Cortex                     | API key                                 |
| Vercel AI Gateway                    | API key                                 |
| ChatGPT / Codex (OAuth)              | Your ChatGPT Plus or Codex account      |
| Anthropic (Claude Code subscription) | A setup token from `claude setup-token` |

The last two options use a personal subscription rather than an API key, and appear only where
Botyard has enabled subscription sign-in. The subscription must be yours, and using it through
Botyard must comply with Anthropic's Terms of Service and Acceptable Use Policy. Botyard does
not extend your subscription terms.

## How credentials are stored

Botyard stores credential metadata separately from the secret values.

| Stored field  | Example                                           | Notes                                                                               |
| ------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Metadata      | provider, label, scope, base URL, default flag    | Stored on the provider credential row.                                              |
| Secret values | provider API key, OAuth access and refresh tokens | Stored together as fields of one encrypted vault entry, linked from the credential. |
| Key prefix    | first safe characters of the key                  | Used for display only, not authentication.                                          |

The vault entry that holds a credential's secrets has no key path of its own; Botyard reaches it
through the credential. Audit events and scanner findings label it
`credentials.<credential_id>`, and a single field as, for example,
`credentials.<credential_id>.api_key`. Those labels are not addresses. Key paths beginning with
`credentials.` are reserved, so a Runtime Vault variable cannot be created under that prefix and
mistaken for a credential's secret.

On the first credential write for an organization, Botyard creates an org tenant keypair. The
secret value is encrypted with age/X25519 before it is stored. The tenant private key is itself
encrypted by the platform master key. Reads decrypt only inside trusted platform services.

## How credentials are injected

Provider calls go through the provider proxy:

1. The bot sends an authenticated request to Botyard's provider proxy.
2. The proxy verifies the bot identity and resolves the bot's linked credential for the
   requested scope and endpoint.
3. The proxy decrypts the credential value inside the proxy process.
4. The proxy scans the outbound request for sensitive Runtime Vault values. In `redact` or
   `strict` mode, a match in the body is redacted before forwarding and a match in the path,
   query string, or headers refuses the request. In `log_only` mode the match is recorded and
   the request is forwarded unchanged. See [Exfiltration scanning](/docs/exfiltration-scanning).
5. The proxy forwards the request to the upstream provider with the provider credential in the
   appropriate authorization header.

The bot's runtime sees the provider response, not the provider credential. Plaintext
credential material is cached only in a short-lived per-pod memory cache. Shared Redis caches
credential metadata only, never plaintext keys.

## Safety pattern

This follows a **brokered credential injection** or **secretless workload** pattern. The bot is
the workload, the provider proxy is the broker, and the secret is injected only on the final
network hop to the provider. This reduces blast radius compared with mounting long-lived keys
into the bot filesystem, environment, or workspace.

The pattern is also close to a policy enforcement point: the proxy can verify bot identity,
choose the allowed credential, scan the outgoing payload, and log the call before any provider
key is attached.

## GitHub App credentials

GitHub App credentials are different from API-key credentials. Installing the GitHub App creates
a provider credential with installation metadata, not a long-lived user token. When Botyard
needs to verify or use the installation, it authenticates as the GitHub App and uses the
installation ID to work with the selected repositories.

See [GitHub integrations](/docs/github-integrations) for the full setup flow.