SpiderGate

SpiderGate authenticates every non-public request with a bearer token, and it accepts two token formats. Pick whichever fits: a client credential for server-to-server use, or a per-agent token for anything you want to budget and observe independently.

The two formats

Client credential

A colon-joined triple of your client id, API key, and API secret:

Authorization: Bearer <client_id>:<api_key>:<api_secret>

This authenticates as your workspace (brand). Use it for trusted backends where one credential represents the whole app.

Agent token (PAT)

A single opaque token, minted in the dashboard:

Authorization: Bearer spideriq_pat_0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d

Agent tokens carry their own budget, rate limits, allowed-models list, and scopes, and resolve to your client_id at auth time — so per-agent controls layer on top of brand identity. This is the recommended format for agents and anything you want to meter separately. Mint one in Agent Keys.

Tip: Behind both formats, client_id is the ground truth — it's what usage, spend, and traces are attributed to. Agent tokens add a layer of per-agent control without changing that identity.

Passing the token

The header is standard for every authenticated call:

curl -X POST "https://spideriq.ai/api/gate/v1/chat/completions" \
  -H "Authorization: Bearer $SPIDERIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "spideriq/fast", "messages": [{"role": "user", "content": "ping"}]}'

With the OpenAI SDK, the token goes in api_key:

from openai import OpenAI
client = OpenAI(base_url="https://spideriq.ai/api/gate/v1", api_key="spideriq_pat_…")

Public endpoints

The read-only catalog endpoints need no authentication:

GET /health
GET /models and GET /models/{model_id}
GET /aliases
GET /providers

Everything that generates or reads your data — chat, images, audio, embeddings — requires a token.

Scopes

Agent tokens are scoped. The gateway scopes are:

gate:chat — chat completions and the multi-modal endpoints.
gate:models — list models and aliases.
gate:usage — read the token's own usage.

New tokens default to all three. See Agent Keys for setting scopes and other per-token controls.

When auth fails

A missing or malformed token returns 401 with a structured body and a WWW-Authenticate: Bearer header. Common codes:

::table
Code | Meaning
`missing_api_key` | No token in the `Authorization` header.
`invalid_token_format` | The token isn't a valid credential triple or PAT.
`invalid_api_key` | The credential or PAT didn't validate.

A valid token that's over budget, rate-limited, or not allowed to use a model returns 402, 429, or 403 respectively — see Errors and Rate Limits & Budgets.

Next steps

Mint a per-agent token — Agent Keys.
Make your first authenticated call — Quickstart.
Handle the error codes — Errors.

Authentication