Provider credentials
Store provider credentials and understand Botyard's in-flight credential injection model.
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
- Sign in to app.botyard.io.
- Open Credentials.
- Choose the tab that matches the credential:
- LLM Providers for OpenAI, Anthropic, OpenRouter, Snowflake Cortex, or compatible APIs.
- Web Search for search providers.
- Integrations for external services such as GitHub.
- Click Add credential.
- 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.
How credentials are stored
Botyard stores credential metadata separately from the secret value.
| Stored field | Example | Notes |
|---|---|---|
| Metadata | provider, label, scope, base URL, default flag | Stored on the provider credential row. |
| Secret path | credentials.<credential_id>.api_key | A pointer to the encrypted value. |
| Secret value | provider API key or OAuth token | Stored in the encrypted secrets store. |
| Key prefix | first safe characters of the key | Used for display only, not authentication. |
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:
- The bot sends an authenticated request to Botyard's provider proxy.
- The proxy verifies the bot identity and resolves the bot's linked credential for the requested scope and endpoint.
- The proxy decrypts the credential value inside the proxy process.
- The proxy scans the outbound request for sensitive Runtime Vault values.
- 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 for the full setup flow.