Authentication and API Keys

All /v1/* requests to Inference Space use a gateway API Key for authentication. The Key format, Authorization header, capability scopes, and authentication error codes are described below.

API Key format

API Keys use the gk_ prefix and are created in the console at https://ai.inf.space. The complete Key is shown once at creation, so store it securely. The console and usage reports show only the Key prefix and never display the complete plaintext again.

gk_1a2b3c4d5e6f7a8b9c0d1e2f

Authentication header

Pass the Key in the HTTP Authorization header using the Bearer scheme:

Authorization: Bearer gk_xxxxxxxxxxxxxx

curl "https://ai.inf.space/v1/chat/completions?provider=anthropic" \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-x",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

import os, requests

resp = requests.post(
    "https://ai.inf.space/v1/chat/completions",
    params={"provider": "anthropic"},
    headers={"Authorization": f"Bearer {os.environ['TOS_API_KEY']}"},
    json={
        "model": "claude-sonnet-4-x",
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
print(resp.status_code, resp.json())

const resp = await fetch(
  "https://ai.inf.space/v1/chat/completions?provider=anthropic",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TOS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "claude-sonnet-4-x",
      messages: [{ role: "user", content: "Hello" }],
    }),
  },
);
console.log(resp.status, await resp.json());

Capability scopes

Each API Key is granted scopes by capability. The gateway determines the required scope from the request path and returns 403 when the Key lacks that scope.

The wildcard scope ai:* grants access to every capability. A Key containing ai:* is not checked for a specific capability on each path.

Authentication error codes

When data-plane authentication fails, the response uses a flat error body: the top-level error field is the error code, and message is a human-readable description. This differs from the nested business-error shape { error: { type, message } }.

Example 401 response for a missing Key:

{
  "error": "missing_api_key",
  "message": "API key required (Authorization: Bearer gk_...)"
}

Example 403 response when an image endpoint is called with a Key that has only ai:chat:

{
  "error": "insufficient_scope",
  "message": "API key lacks scope for /v1/images/generations"
}

Troubleshooting:

• For missing_api_key, confirm that the request includes Authorization: Bearer gk_..., including the Bearer prefix and the space.
• For invalid_api_key, confirm that the Key is correct, has not expired, and has not been revoked in the console.
• For insufficient_scope, add the required capability scope to the Key in the console (for example, image endpoints require ai:image) or use a Key with sufficient permissions.

Integration recommendations

• In production, keep API Keys on the server and do not expose them to browsers or clients.
• Use different Keys for different applications to simplify auditing, quotas, and revocation.
• Grant only the minimum capabilities required and avoid sharing a high-privilege ai:* Key long term.

See Quickstart and Model discovery and catalog for more information.