BYOK — bring your own key

BYOK lets you attach your own model-provider credentials to your Square1 account and call those providers through the same /v1/chat/completions endpoint. Your requests then run on your credential and your provider account’s billing — Square1 is the relay.

BYOK availability is an operator switch. When it’s off, BYOK model ids return 403 byok_disabled.

Register a credential

Credentials are managed in the dashboard’s BYOK page — you pick a provider, paste your key (plus provider-specific settings like region or project where relevant), and the dashboard verifies the credential with a live test call before saving. Secrets are write-only: once saved, they are never displayed again. Supported provider types include Anthropic, OpenAI, Google AI Studio, DeepSeek, OpenRouter, LLM Gateway, AWS Bedrock, Vertex AI, and any OpenAI-compatible endpoint (compat).

Call a BYOK model

Prefix the model id with @:

@<provider>/<upstreamModelId>
@<provider>:<label>/<upstreamModelId>

The second form picks a specific credential by its label when you have several for one provider.

curl https://inference.square1.dev/v1/chat/completions \
  -H "Authorization: Bearer $SQUARE1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "@openai/gpt-5.1",
    "messages": [{"role": "user", "content": "Hello via my own key!"}]
  }'

<upstreamModelId> is the model id as your provider names it — Square1 forwards it verbatim and does not maintain a catalog for your provider. For the same reason, BYOK models do not appear in GET /v1/models.

Error surface

HTTP	`code`	Meaning
403	`byok_disabled`	The BYOK feature is currently off
400	`byok_credential_missing`	No usable credential matches the `@provider` reference (unknown provider, missing credential, or incomplete settings)
5xx	`byok_upstream_error`	Your provider’s endpoint failed

Because you own the upstream relationship, failures on your BYOK requests can include your provider’s own error details — visible only to you, on your requests.

Anything you send through a BYOK model is processed by your provider under your agreement with them. Square1’s pool quotas and model caps are about shared capacity; your BYOK usage is billed by your provider, not by the pool.

Getting started

Core concepts

Guides

Public data

BYOK — bring your own key

Register a credential

Call a BYOK model

Error surface

​Register a credential

​Call a BYOK model

​Error surface

Register a credential

Call a BYOK model

Error surface