CosavuCosavu

Getting started · Authentication

Authentication

Every request to the Cosavu API requires an API key. Keys identify your project, scope your access, and meter your usage. They're managed entirely from the dashboard.

Getting an API key

Sign in to the Cosavu dashboard, open the Keys tab inside your project, and click Create new key. You'll see the full key value once — store it immediately.

Important

API keys are shown in full only once at creation time. Save the value to a secrets manager immediately. If you lose it, you'll need to rotate the key and update your integrations.

Test vs live keys

Every project has two parallel environments. Test keys are free and rate-limited; live keys are billed and unmetered.

PrefixEnvironmentBehaviour
cv_test_Test modeFree, rate-limited to 10 req/s. Results may be cached.
cv_live_ProductionBilled per usage. Full rate limits apply.

Using your key

Store your key as an environment variable. Both SDKs pick it up automatically from COSAVU_API_KEY:

# .env
COSAVU_API_KEY=cv_live_a1b2c3d4e5f6...
import { Cosavu } from "@cosavu/sdk"
 
// Reads COSAVU_API_KEY from process.env automatically
const cosavu = new Cosavu()
 
// Or pass explicitly
const cosavu2 = new Cosavu({ apiKey: "cv_live_..." })

Direct HTTP requests

If you're not using an SDK, send the key in the Authorization header as a Bearer token:

$ curl https://api.cosavu.com/v1/context/optimize \
  -H "Authorization: Bearer $COSAVU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello world"}'

Scopes

Keys can be limited to specific products. Useful for backend services that only need one API:

ScopeGrants access to
context:readContextAPI parse and inspection endpoints.
context:writeContextAPI optimisation endpoints.
data:readDataAPI query endpoints.
data:writeDataAPI ingest, delete, and admin endpoints.
agent:runVexaAgent execution.
*All scopes (default for new keys).

Rotating keys

Rotate keys at any time from the dashboard. Both old and new keys remain valid for 24 hours by default, giving you a grace period to roll out the new key:

  1. Create a new key in the dashboard.
  2. Update your secrets manager with the new value.
  3. Re-deploy services that consume the key.
  4. Confirm metrics show traffic on the new key.
  5. Revoke the old key.

Security best practices

  • ›Never commit keys to source control. Add .env to your .gitignore.
  • ›Never expose keys client-side. Always proxy through your own backend.
  • ›Create separate keys per environment (dev / staging / prod) so you can rotate independently.
  • ›Use the narrowest scope a service needs. A read-only worker doesn't need write keys.
  • ›Set a spend cap on every key. Configure it in the dashboard's billing settings.
← InstallationContextAPI →