Authentication

Every API call goes to https://api.kunavo.com/v1 with Authorization: Bearer sk-kn-XXX. That's it.

Base URL

The single endpoint that fronts every model, every modality.

The path layout follows OpenAI's conventions:

API keys

API keys are issued from /app/keys in the dashboard. Each key:

• Starts with sk-kn- followed by 30+ random characters.
• Is shown once at creation — Kunavo only stores a hash afterwards.
• Has a human-readable name (e.g. prod-web) for the dashboard.
• Can be revoked at any time — the key 401s instantly after revocation.
• Can carry its own monthly spend limit and IP allowlist, both set from /app/keys and both enforced on every call.

Per-key spend limits (optional)

For each key you can set a monthly spend limit in dollars. Once that key's settled usage for the current calendar month would pass the limit, calls made with it return 402 insufficient_quota and nothing is charged, until the limit resets at month start. Your other keys are unaffected — this is a ceiling on one credential, not on the account.

That is the containment an unattended agent actually needs: the wallet balance is shared by every key, so on its own it cannot stop one runaway loop from spending everything. Give the agent its own key with a limit sized to the job, and the worst case is bounded by that number. A limit of $0 pauses a key without revoking it.

Per-key IP allowlist (optional)

A key can also be restricted to a set of addresses. Enter one IPv4/IPv6 address or CIDR block per line (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); calls presenting that key from anywhere else are refused with 403 permission_error, on every endpoint including /v1/models. Leave it blank to allow any address.

Request headers

The minimum required headers on every request:

Authorization: Bearer sk-kn-...
Content-Type: application/json

Optional but recommended: User-Agent identifying your app. We log user-agents in your /app/usage dashboard for debugging request sources.

Using the OpenAI SDK

Most teams stay on the official OpenAI SDK and just swap base_url. Both Python (v1.x+) and Node (v4.x+) work this way.

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KUNAVO_API_KEY"],
    base_url="https://api.kunavo.com/v1",
)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KUNAVO_API_KEY,
  baseURL: "https://api.kunavo.com/v1",
});

Key rotation

Best practice: rotate API keys quarterly or whenever a key may have leaked. Kunavo lets you have multiple keys per account simultaneously, so rotation is a clean overlap, not a flip.

# 1. Create a new key in /app/keys, set its name to e.g. "prod-2026-Q2"
# 2. Deploy new key to your servers
# 3. Verify traffic is flowing on the new key (dashboard shows usage)
# 4. Revoke the old key from /app/keys → it 401s immediately

# In code, swap one env var:
export KUNAVO_API_KEY="sk-kn-new-..."

Security notes

• Never expose keys client-side. Browser code and mobile bundles are public. Always proxy through your server.
• Scope keys narrowly. Different keys per project let you revoke without affecting other workloads — and let each one carry its own spend limit and IP allowlist, so a leaked key is bounded in both cost and origin.
• Watch the dashboard. The /app/usage page shows traffic broken down by key — unexpected activity is easier to spot.
• Report suspected leaks. Email support@kunavo.com and we'll help with key invalidation and incident review.

Where to go next

• Chat completions reference
• Error codes and retry strategy