Authentication

API reference

Requests to the Zukko API are signed with a fetch_... key. Create it on the API keys page; it is shown only once.

1How to send the key

Either of two headers works:

bash

Authorization: Bearer fetch_YOUR_KEY
x-api-key: fetch_YOUR_KEY

Authorization: Bearer is what the OpenAI SDK and most IDEs use. x-api-key is sent by the Anthropic SDK, Roo Code, and other Anthropic clients — no need to change their settings. Passing the key in the query string (?api_key=...) is not supported: such a request gets 401.

2anthropic-version

Zukko neither checks nor requires this header. If your client sends it (the Anthropic SDK does so automatically), it is passed to the provider as is — keep it.

3What needs a key

Endpoint	Key
`GET /v1/models`, `GET /v1/models/{id}`, `GET /v1/models/info`	not needed, the key is ignored
`GET /api/status`	not needed
`GET /v1/balance`, `GET /v1/usage`	required
`POST /v1/chat/completions`, `/v1/messages`, `/v1/messages/count_tokens`, `/v1/responses`, `/v1/images/generations`, `/v1/web-search`	required, plus a verified email and a balance of at least $0.01

One key works with every endpoint and every model, unless the key's settings restrict the model list.

4Authentication errors

Missing key, typo, revoked key — 401:

json

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Use Authorization: Bearer fetch_*. Поддержка — https://t.me/zukkopro?direct, напишите, пожалуйста."
  }
}

The support line at the end of the message is added to every Zukko error. Unverified email — 403 with code email_unverified. All other codes are in API errors.

5Example

bash

curl https://api.zukko.pro/v1/balance \
  -H "Authorization: Bearer fetch_YOUR_KEY"

6Security rules

use HTTPS only: https://api.zukko.pro;
keep the key out of code and repositories — read it from environment variables;
create a separate key per app and give it limits: a leaked key can be revoked without touching the others.

OpenClaw

API errors