Bring your own key (BYOK)
Learn how to bring your own OpenAI key to use the Soda AI features
Bring your own key is only available in organizations fully on Soda v4.
Migrate to Soda v4 to have access to the newest Soda capabilities.
Bring-your-own-key (BYOK) lets you point Soda's AI-backed features at an OpenAI account that you own and control, instead of the OpenAI project Soda operates on your behalf. Once a feature is bound to a provider that uses your key:
Your data stays in your OpenAI workspace. Every AI request the feature makes (Ask AI prompts, Contract Copilot generations, Autopilot runs) is sent directly to your OpenAI project. None of it passes through Soda's OpenAI project, and the privacy, retention, and regional-routing terms that apply are the ones you have configured on your own OpenAI account (for example workspace-level data-retention settings or a zero-retention agreement).
You stay in control of the key. Soda never stores the raw key; it stores a reference to where the key lives (an environment variable on your infrastructure, or a Soda Cloud secret you manage). Rotation and revocation happen in the system you already use, with no need to involve Soda support.
You can mix and match. Some capabilities can stay on the Soda built-in provider (and continue to be covered by your Soda subscription) while others run against your own key.
AI configuration
Soda's AI-backed features run on a configurable provider layer. By default, every organization uses the Soda built-in provider, which is managed end-to-end by Soda. If you want those features to run against your own OpenAI account instead, you can add a custom provider and bind it to the features you choose.
Organization settings - AI tab visibility
The AI tab (LLM) in Organization settings is shown only when at least one AI-backed feature is enabled for your organization. If every AI-backed feature is currently disabled, the tab is hidden, because there is nothing to configure.
Providers
The Providers section of the AI tab lists every provider available to your organization.
Soda's built-in provider
The Soda (OpenAI) card is always present and is always shown first. It represents the AI endpoint that Soda manages on your behalf, and it:
is included with your Soda subscription,
cannot be edited or removed, and
has no settings of its own: there is no API key to rotate, and the model is chosen and maintained by Soda.
If you only use the built-in provider, no further setup is required: every AI-backed feature is bound to it by default.
Add a custom OpenAI provider
Click Add provider at the end of the providers list to open the Add provider dialog.
Fill in:
Type — currently only OpenAI is available.
Name — a name that identifies this provider in the providers list and in the feature-configuration dropdowns. Choose a label that makes it easy to recognize which key it represents, for example
Acme prod OpenAI.API key — a reference to where the key is stored. Soda never stores the raw key itself; instead, the value you enter here points to the location Soda should read at run time. The field accepts two reference formats, described in the next section.
When you click Save the new provider appears in the providers list and becomes selectable in every feature-configuration box.
API key reference formats
The API key field accepts one of two reference formats: environment variable, or Soda Cloud secret. Soda resolves the reference at run time and uses the real value only in memory; the raw key is never written to Soda Cloud's storage.
1. Environment variable — ${env.NAME}
Use the ${env.NAME} format when the key is set as an environment variable on the self-hosted agent.
At run time, Soda reads the named environment variable from the host's environment. The value never enters Soda Cloud and is never visible in the secrets UI. It lives entirely in your own infrastructure.
This option is recommended when:
you already manage credentials through your platform's environment (for example Kubernetes secrets mounted as environment variables, AWS Parameter Store injected at boot, or a
.envfile on a self-hosted machine), oryou prefer the key to remain entirely outside Soda Cloud.
Storing the key as an environment variable will not work with the Soda AI feature because it is a Soda-managed service, and you do not have control over the environment variables.
2. Soda Cloud secret — ${secret.NAME}
Use the ${secret.NAME} format to reuse Soda Cloud's built-in secrets manager. The referenced secret must already exist under Organization settings → Secrets. The reference looks like:
At run time, Soda looks up the secret in your organization's encrypted secret store and uses its value in memory. This option is recommended when:
you don't run a self-hosted agent and have nowhere to set environment variables, or
you prefer to manage every credential in one place, using the same rotation and access controls you already use for warehouse passwords and other secrets.
A ${secret.…} reference creates a live link between the provider and the secret. While any AI provider's API key still points at a given secret, Soda Cloud prevents that secret from being deleted; the deletion dialog lists the affected providers and asks you to update them first.
Manage existing providers
Each custom provider has a three-dot menu with a Remove action. A provider can only be removed when no feature is currently bound to it. If a feature still uses the provider, the removal is blocked and Soda tells you which capabilities to reassign first.
The Soda built-in provider has no menu and cannot be removed.
Attach a provider to a feature
Below the providers list, the Feature configuration section allows you to bind each AI-backed capability to a provider:
Capabilities that are disabled for your organization are not shown.
What each capability covers
Soda AI powers Ask AI and Contract Copilot. You can point this capability at any provider, including your own OpenAI account, but the model used for Soda AI is fixed by Soda. There is no Model field, because the model is chosen by Soda to match the prompts that ship with these features.
Runner powers Autopilot. The Runner box also includes a Model field where you can specify the model your provider should use (for example
gpt-4oorgpt-4o-mini). If you leave the field empty, the provider's default model is used.
Bind a feature
In the capability's box, open the Provider dropdown.
Choose Soda (OpenAI) to keep the feature on the built-in provider, or choose any custom provider you have added.
For Runner, optionally enter the model name in the Model field.
Click Save at the bottom of the section.
The new binding takes effect on the next run of that feature.
Switch back to the built-in provider
If a custom provider is bound to a capability and you want to revert:
Open the capability's box.
Set the Provider dropdown back to Soda (OpenAI).
Click Save.
Once no capability is bound to a custom provider, you can remove that provider from the providers list.
Troubleshooting
The AI tab is missing from Organization settings.
At least one AI-backed feature must be enabled for your organization: Ask AI, Contract Copilot, or Autopilot. If all three are disabled, the tab is intentionally hidden.
The Add provider dialog rejects the API key.
The key must be a ${env.NAME} or ${secret.NAME} reference. Plain strings, empty values, and other ${…} formats are not accepted.
Removing a provider fails with a message naming a capability.
The provider is still bound to that capability. Open Feature configuration, change the named capability to a different provider, save, then remove the provider again.
A ${secret.NAME} reference does not resolve at run time.
Make sure the secret still exists under Organization settings → Secrets and that its name matches the reference exactly. Secret names are case-sensitive.
A ${env.NAME} reference does not resolve at run time.
Make sure the environment variable is set in the process that runs Soda (for example, the self-hosted agent) and that the variable name matches exactly. Environment variable names are case-sensitive.
You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.
If you do have a Soda license, make sure to log in to Soda Cloud in this same browser.
Last updated
Was this helpful?