Bring your own LLM keys (BYOK)

Use bring your own key (BYOK) to route OneSchema's AI features through your own LLM provider account. Instead of using OneSchema's managed provider credentials, you create a connection with your API key, choose which models you have deployed, and map those models to the OneSchema AI features you want to power.

📘

This guide covers configuring BYOK. For an overview of what OneSchema's AI features do, see Using OneSchema AI.

Availability

BYOK is available for organizations that have the feature enabled. Contact your OneSchema account team or [email protected] to turn it on. You need the Admin or Developer role in your OneSchema organization to create or edit LLM provider connections.

Why use BYOK

• Control credentials. Your API keys are stored encrypted in OneSchema and are used only for your organization's AI calls.
• Use your own provider agreements. Data is sent to the LLM provider under your account, so your existing agreements with the provider — including any DPAs, BAAs, and rate limits — apply.
• Pick specific models. Map the exact deployment names or model IDs available in your provider account to the OneSchema features that use them.

Supported providers

You can connect the following providers through BYOK:

Before you begin

1. Make sure you have an active account and API key with the provider you want to use.
2. Confirm the models you plan to use are available in that account:
   • For OpenAI, this is the model name or model ID your key can call.
   • For Anthropic, this is the model name your key can call.
   • For Azure OpenAI, this is the deployment name you assigned when you deployed each model in your Azure OpenAI resource.
3. Ask your OneSchema account team to enable BYOK for your organization.

Create an LLM provider connection

1. In the OneSchema dashboard, go to Developer → AI Settings.
2. Open the LLM Provider Accounts tab.
3. Click Create connection and select the provider you want to add.
4. Enter a descriptive Connection name so you can identify it later.
5. Enter the provider details:
   • API key: Your active API key for that provider.
   • Endpoint / API base URL (OpenAI and Azure OpenAI only): The base URL for the provider.
     • Azure OpenAI: required. Use the resource endpoint shown in your Azure portal.
     • OpenAI: optional. Leave blank to use the default OpenAI platform endpoint, or enter a custom OpenAI-compatible endpoint.
     • Anthropic: not shown; the connection uses Anthropic's platform endpoint.
6. Map the models:
   • Azure OpenAI: enter the Azure deployment name for each OneSchema model you have deployed. Leave blank any models you have not deployed.
   • OpenAI with custom base URL: enter the model name or deployment name each provider model maps to. Leave blank models you have not deployed.
   • OpenAI (default endpoint) and Anthropic: check the box for each model your API key can access. Only checked models are tested and can be selected for OneSchema AI features.
7. Toggle Use as default [provider] provider if this should be the default connection for that provider.
8. Click Test connection to verify the endpoint, API key, and each mapped model.
9. Click Create connection to save.

You can create multiple connections for the same provider. By default, the first connection you save for a provider is set as the default, but you can turn off the Use as default [provider] provider toggle before saving or change it later by editing the connection.

Map models to features

After you create a BYOK connection, choose which model each OneSchema AI feature uses.

1. Go to Developer → AI Settings.
2. Open the Model usage across OneSchema tab.
3. Choose the model you want for each AI feature category shown. The tab lists one row per feature, including:
   • Code generation with AI — for template hooks, custom code actions, and AI-powered Transforms.
   • Data mapping with AI — for AI-suggested column and picklist mappings in the Importer.
   • Categorize data with AI.
   • Extract data with AI — for the Extract Data transform in Multi FileFeed.
   • PDF extraction with AI — for structured PDF extraction and Split PDF by content in Multi FileFeed.
   • Importer PDF extraction — for PDF extraction in the embedded Importer.
   • Extract PDF to Markdown.
   • FileFeed agents — for the CSV agent in Multi FileFeed.
   • File agent — for the file agent in Multi FileFeed.
   • Feed Builder Agent.
   • AI code review — for code-based Transforms in Multi FileFeed.
   • OneSchema Studio.
   • Inspector Agent.
4. Click Save changes to apply your selections.

Only models that have been mapped in a connection and that belong to an allowed provider appear in the model dropdowns. If you do not see a model you expect, return to the LLM Provider Accounts tab and confirm the connection is tested and the model is mapped. If the connection is correct but the provider is not listed, contact your OneSchema account team — provider allowlisting is managed on your behalf.

Connection testing

When you test a connection, OneSchema:

1. Verifies the endpoint and API key authenticate successfully.
2. Makes a small test call to each mapped model to confirm it is reachable.

If the test fails, the error message describes which step failed:

• Invalid API key or insufficient permissions: the API key was rejected or does not have access to the endpoint.
• Endpoint not found: the base URL or resource name is incorrect, or the Azure OpenAI URL does not match the required hostname pattern.
• Deployment or model not found: a mapped model or Azure deployment name does not exist in the provider account.
• Rate limited: the provider rejected the request due to quota limits. Try again later.
• Could not reach endpoint: the URL is unreachable or invalid.

Security and data handling

• Your API keys are stored encrypted at rest and are never returned in dashboard or API responses.
• When using BYOK, requests are sent directly to your provider account. Your data is handled under your agreement with the provider and your provider's data retention and privacy terms.
• For more details on how data is shared with LLM providers, see the Using OneSchema AI FAQ section.

Limits worth knowing

• You can create multiple connections per provider, but each connection maps one set of credentials and one set of model deployments.
• A model must be both allowed at the provider level and mapped in a connection before it can be selected for a feature.
• Custom OpenAI-compatible endpoints must be reachable over public HTTPS. Private, loopback, link-local, or internal addresses are rejected for security reasons.
• Azure OpenAI endpoints must be the .openai.azure.com resource root (for example, https://<resource>.openai.azure.com/) or end with the /openai/v1 Foundry path. A trailing slash is optional in both cases.

Edit or delete a connection

1. Go to Developer → AI Settings and open the LLM Provider Accounts tab.
2. Find the connection in the list.
3. Open the actions menu and choose Edit or Delete.

Editing a connection re-runs the connection test. Deleting a connection removes it immediately. If a feature was using a model from that connection, OneSchema tries to use another connection for the same provider that maps the same model. If no other connection maps that model, the feature will not work for that model until you create or edit a connection that maps it again.