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

# BYOK — bring your own key

> Route requests through your own provider credentials

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.

<Note>
  BYOK availability is an operator switch. When it's off, BYOK model ids
  return `403 byok_disabled`.
</Note>

## 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 `@`:

```text theme={null}
@<provider>/<upstreamModelId>
@<provider>:<label>/<upstreamModelId>
```

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

```bash theme={null}
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.

<Warning>
  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.
</Warning>