Authentication

Every CanalAPI request is authenticated by API key. The same key works for the OpenAI-compatible endpoints, Anthropic Messages, and the Gemini native endpoints.

Where to get a key

See API Keys for the console workflow. Keys are issued in the format sk-....

How to send the key

1. Authorization: Bearer (recommended, universal)

Works for every endpoint:

POST /v1/chat/completions HTTP/1.1
Host: api.canalapi.com
Authorization: Bearer sk-your-key
Content-Type: application/json

Any client that accepts a custom baseURL + apiKey works the same way:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.CANALAPI_API_KEY,
  baseURL: 'https://api.canalapi.com/v1',
});

2. x-api-key (Anthropic clients)

If your codebase already uses the Anthropic SDK:

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.CANALAPI_API_KEY,
  baseURL: 'https://api.canalapi.com',
});

The server accepts both Authorization: Bearer and x-api-key; no further changes are needed.

3. x-goog-api-key or ?key= (Gemini-native clients)

The Gemini-native endpoints (/v1beta/*, /v1/models/:model:generateContent, …) accept three forms of auth:

GET /v1beta/models?key=sk-your-key

POST /v1beta/models/gemini-1.5-pro:generateContent
x-goog-api-key: sk-your-key

Authorization: Bearer also works.

Per-key access controls

Every key can be configured independently in the console:

• Quota cap — total USD a key may spend (independent of the account balance)
• Allowed models — model allowlist; calls to other models return 403
• IP allowlist — restrict callers by IP / CIDR
• Expiration — auto-invalidate after a date

See API Keys for the full set; rate-limit behaviour is in Rate Limits.

Failure modes

Full error model: Errors.

Console login vs. API key

Console sign-in and API requests use two independent credentials:

• The console at https://www.canalapi.com uses email + password, with optional 2FA and active-session management — see Security.
• The API is authenticated by API key only; no cookies / sessions.

Revoking a key does not sign you out of the console. Changing the password does not invalidate existing keys.

Operational notes

• Never commit a key to source control or paste it into screenshots / tickets.
• Never embed a key in browser JavaScript or a mobile app. Use a server-side proxy.
• Inject keys via Secrets / environment variables in CI and production.
• Rotate keys when team members leave or when you suspect leakage.
• Use separate keys per environment (dev / staging / prod) for surgical revocation and clean billing attribution.