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

# Bring Your Own Key (BYOK)

> Connect your own AI provider, choose supported models, and pay your provider directly for inference.

Zenable can run its AI work on an endpoint you supply. Your provider bills you
directly for requests sent to your endpoint, and you choose a supported model
for each capability level. Zenable Credits still apply at the BYOK rates in
[Plans and Usage](https://docs.zenable.io/plans-and-usage.md#credit-cost-per-file).

> [!NOTE]
>
> **Plus** requires BYOK and does not allow Zenable-managed generative inference.
> **Enterprise** lets your company choose whether BYOK is required. **Free** and
> **Professional** use Zenable-managed inference and cannot configure BYOK. See
> [Plans and Usage](https://docs.zenable.io/plans-and-usage.md).

## What your endpoint must support

Your provider must expose an OpenAI-compatible model catalog. For inference,
Zenable supports **OpenAI Chat Completions** and **Anthropic Messages**. A provider
can expose the catalog and inference APIs at different paths on the same host.
API compatibility alone does not make every model eligible: the model must also
match a supported capability level.

**1. Public HTTPS endpoint**

The base URL must use HTTPS and resolve to a public address. Credentials
embedded in the URL, query strings, and fragments are rejected. An endpoint
that is only reachable inside your network cannot be used.

**2. OpenAI-compatible model catalog**

Zenable calls `{base_url}/models` with your key as a bearer token. The
response must contain a nonempty `data` array of model entries with IDs.
Empty or malformed catalogs are refused when connecting.

**3. A supported inference API**

Choose **OpenAI Chat Completions** (`POST /chat/completions`) or
**Anthropic Messages** (`POST /messages`) for each capability level.
The selected model must support text input and output, and tool calling
where required. Access to the model catalog does not prove permission to
invoke a model or compatibility with the chosen inference API.

## Capability levels

Choose one model for each level. The model picker shows eligible models from
your provider's catalog.

| Level | Description |
| - | - |
| **Premium** | Used for complex tasks that require the highest reasoning quality. |
| **Fast** | Balances quality and speed while keeping costs low. |
| **Simple** | Optimized for speed and low cost, for tasks that don't require advanced reasoning. |

On Plus, or when your Enterprise company requires BYOK, all three levels must
have a model from your provider before AI work can run. With optional BYOK on
Enterprise, levels without your own model can use Zenable-managed inference.

> [!TIP]
>
> A model can appear in your provider's catalog without being eligible for a
> particular level. If no models are offered, contact support before choosing a
> provider or deploying a model. Catalog eligibility does not guarantee that every
> provider implements streaming or tool calling in the same way.

## Connecting

On Plus or Enterprise, open **Settings → BYOK**. Viewing the settings requires
`settings:read`; connecting a provider or changing models requires
`settings:manage`.

**1. Connect your provider**

Enter the base URL for your model catalog and an API key. Choose
**Verify and continue** to check access to the catalog. The settings page
displays a masked key with its last four characters; the full key is never
returned by the API.

**2. Choose models and API formats**

Select a model for Premium, Fast, and Simple. For each one, choose the
**API format** supported by your provider and, if needed, a **Base path**.
Save the model configuration.

**3. Run a small request**

Confirm that a real request completes with the selected models. A successful
catalog check does not verify inference permissions, streaming, or tool
calling. If an operation fails, follow its feedback and review the warning
on the BYOK settings page when one is present.

### API format and base path

Without a Base path override, inference uses the endpoint URL you connected.
An override replaces its path while keeping the same HTTPS host and credential.
Enter the API base path, without `/chat/completions` or `/messages`.

For example, a provider can list models at `https://models.example.com/v1/models`
and serve OpenAI Chat Completions at
`https://models.example.com/openai/v1/chat/completions`. Connect
`https://models.example.com/v1` and set that model's Base path to `/openai/v1`.
For Anthropic Messages at `https://models.example.com/anthropic/messages`, select
**Anthropic Messages** and set Base path to `/anthropic`.

Choose the format based on the API your provider exposes, not the model's name.
A Claude model behind an OpenAI-compatible gateway can use OpenAI Chat Completions.

## Requiring BYOK and handling failures

On **Plus**, BYOK is always required and cannot be turned off. A missing model
assignment or provider failure prevents the AI operation from completing;
Zenable does not switch it to managed inference.

An **Enterprise** company administrator with `company:manage` can enable or
disable **Require BYOK** in Settings → BYOK. This setting applies across the
company's workspaces. When enabled, every workspace needs its own configured
provider and all three model levels. When disabled, work without an assigned
customer model can use Zenable-managed inference.

> [!NOTE]
>
> Automatic fallback from a failing BYOK request to another model, provider, or
> Zenable-managed inference is not supported. An operation can retry the same
> route a limited number of times; if it cannot complete, it reports a failure.

## Output token limits

The BYOK page lets you limit the length of model responses. A provider connection
override takes priority over a provider-specific default configured by Zenable,
which in turn takes priority over the workspace override. If none is set, a
model-specific limit or the BYOK default applies. The provider's advertised hard
limit can reduce the effective maximum. These settings limit output tokens, not your
provider's total spend or the size of the input context.

A very small output limit can be consumed by a model's reasoning before it
produces visible text. Increase the limit or ask for a shorter response if the
operation cannot finish. If the selected model's input capacity is unknown,
work that requires a capacity check can be refused before inference.

## Keys and rotation

Your API key is stored encrypted and scoped to the workspace that supplied it.
To rotate it, connect again with the new key. Allow time for configuration
changes to propagate before testing new work.

Disconnecting removes Zenable's stored credential and model assignments. It does
not revoke the key at your provider; revoke it there separately if it is no
longer needed.

> [!WARNING]
>
> Disconnecting while BYOK is required stops AI work until a provider and all three
> model levels are configured again. Deterministic verifier rules and static
> analysis do not need your provider. Rotate by connecting the replacement key
> before revoking the old one.

## What still runs on Zenable

Embeddings, used for search and retrieval, remain Zenable-managed. They are not
covered by the BYOK configuration. The managed decision-model gate is skipped
for BYOK reviews; it is not replaced by a model from your provider.

The assigned models handle chat, code review, conformance checks, and analysis.
BYOK does not change which product features your plan includes.

## Troubleshooting

| Symptom | What to check |
| - | - |
| "Endpoint URL must use HTTPS" | Use an HTTPS URL with a host. |
| "Endpoint returned no available models" | Check that the key can list at least one model. |
| "Endpoint returned an invalid model catalog" | The catalog must use the OpenAI-compatible shape. Use the catalog API base URL, not a model or UI page. |
| Cannot connect | Check public reachability, DNS, and the key's catalog permissions. |
| A model is missing from the picker | Check whether it matches an eligible model for that capability level and advertises the required capabilities. |
| Connected, but an operation fails | Check inference permissions, the chosen API format and Base path, provider quota, and model support for streaming and tools. |
| BYOK is required but work does not start | Configure an active provider and a model for all three capability levels in every workspace that needs AI work. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.