BYOK

Bring your own key (BYOK) lets your organization call a model provider through R9S using your own provider credentials. Applications still call the R9S gateway with an R9S-issued key; the gateway selects the connection and injects the provider credential on the server.

BYOK requests do not consume R9S wallet balance or Token Plan allowance. Your provider can still charge for the upstream request. The sale and cost amounts shown in R9S are based on your organization’s configured BYOK pricing, not a fetched provider invoice.

Before you start

• Select the organization that will own the connection and usage records.
• An organization OWNER or ADMIN must create or manage connections. Members can use connections they are authorized to access.
• Have a provider API key, the provider’s HTTPS API base, and an upstream model ID supported by your account.
• BYOK must be enabled in your deployment. If the controls are unavailable, ask your administrator or R9S support; creating a standard key alone does not enable BYOK.

Never use the provider API key as the bearer token sent to R9S, or place either credential in browser code.

Create a model connection

Open Model Connections in the Console and choose Add connection.

1. Choose a provider preset or configure a custom provider.
2. Enter a Provider Name, one protocol, its API base, and the provider API key.
3. Use Fetch models when available, or add models manually. For each model, set its display name, model slug, and exact upstream model ID.
4. Configure sale and cost prices per one million tokens. If needed, configure peak / flat / valley prices and their time periods.
5. Choose Validate and save, then wait for the connection to become ACTIVE before sending traffic.

Validation during creation and credential rotation sends a one-token test request and may incur a small provider charge. Fetching a catalog does not prove that all models or optional features are available to your provider account.

Provider names must start with an English letter and contain only English letters, digits, _, +, or -. The public prefix is normalized and must be unique. Choose the name carefully: the Console does not allow changing it after creation because it determines public model IDs.

Choose the protocol and endpoint

Each connection uses one protocol. Create another connection if you need a different protocol, even for the same provider.

These are protocol shapes, not interchangeable provider addresses. Use the base supplied by your provider. The provider API base is configured in the connection; your application continues to call https://gw.r9s.ai.

Gemini is the upstream protocol: R9S adapts Chat Completions to it. Native Gemini generateContent passthrough does not inject BYOK credentials. BYOK embeddings are not supported. Other optional features depend on the selected protocol, model, and provider; listing a model does not certify tools, vision, or structured output support.

Production deployments restrict provider API bases to approved HTTPS hosts. If a host is rejected, ask an administrator to approve it; do not work around this with internal, private-network, or metadata-service URLs.

Authorize an R9S key

The current Console flow is under API Keys:

1. Select the same organization as the connection.
2. Create or edit a standard API key.
3. Enable Allow BYOK providers and select the connection under Allowed BYOK providers.
4. Save the key and store the newly created secret securely. Check expiry, RPM, TPM, and any model restrictions before use.

This is still a standard key with explicit BYOK-provider access, not a Token Plan Key. It can also carry ordinary platform-model access under its normal scopes and billing rules. Enabling a provider does not make a standard key BYOK-only or give it the independent admission behavior of a dedicated BYOK key.

Dedicated BYOK keys may also exist in your deployment; they are limited to their authorized BYOK model scope. A Router key can select a BYOK target through a routing profile. Do not substitute a Plan Key for any of these flows.

Find the public model ID

Applications use the public ID displayed by the connection, not its upstream model ID or internal gateway identifier:

custom-<provider-name>/<model-slug>

For example, a connection named Team-Provider with slug chat exposes custom-team-provider/chat. This is an illustrative alias: copy the actual ID from your own connection and confirm discovery with the same authorized key.

export R9S_BYOK_API_KEY="<R9S_KEY_WITH_BYOK_ACCESS>"

curl https://gw.r9s.ai/v1/models \
  -H "Authorization: Bearer $R9S_BYOK_API_KEY"

Send a request

For an OpenAI-compatible Chat Completions connection, replace the example model ID with your connection’s public ID:

curl https://gw.r9s.ai/v1/chat/completions \
  -H "Authorization: Bearer $R9S_BYOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "custom-team-provider/chat",
    "messages": [{"role": "user", "content": "Hello through my provider connection."}],
    "max_tokens": 64,
    "stream": false
  }'

A successful Chat Completions response contains choices and, when the provider reports it, usage. For streaming, use stream: true with curl -N and handle SSE. For Responses or Messages connections, use the matching endpoint and payload instead of reusing this Chat Completions body.

Do not send api_key, api_base, provider-selection fields, or fallback configuration in the inference payload. Credentials and routing are selected from authenticated server-side configuration; client credential or route injection is rejected.

Usage, rotation, and disabling

• Review BYOK Usage in the Console for model, tokens, sale amount, cost amount, and pricing time slot. Each request uses the price snapshot selected when it ran; later price edits do not rewrite that snapshot.
• BYOK usage is attributed separately from platform balance and Plan usage. A standard key with provider access can generate both platform and BYOK records depending on the requested model.
• Rotate provider credentials from Model Connections. R9S stores provider secrets encrypted and returns only masked previews. Rotation can briefly reject new requests while configuration is synchronized.
• Disabling or deleting a connection stops new requests once the route change propagates; already admitted requests may finish. Key expiry, revocation, and organization membership still apply.
• There is no fallback to platform credentials. Missing routes, unavailable credentials, or synchronization failures reject the BYOK request rather than silently spending R9S balance or Plan allowance.

Troubleshooting

For support, provide the request ID, time, public model ID, and connection status, never the provider secret. Continue with Router to combine target types, or Agent Trace to correlate agent requests.