Authentication

CaviusConnect uses bearer-token API keys. Every request carries your key in the Authorization header:

Authorization: Bearer ck_live_...

Key types

Creating a key

Create keys in the dashboard under Developer → API keys, or via the API:

const created = await client.apiKeys.create({
  name: "Webhook receiver",
  scopes: ["messages:read", "webhooks:write"],
});
console.log("Save this once:", created.apiKey);

created = client.api_keys.create(
    name="Webhook receiver",
    scopes=["messages:read", "webhooks:write"],
)
print("Save this once:", created["apiKey"])

The full key is returned only on creation and never again. If a key is lost, revoke it and create a new one.

Scopes

Keys are scoped server-side using resource:action permission strings, for example contacts:read, messages:send, webhooks:write. A request made with a key missing the required scope fails with 403 Forbidden. Grant each key the minimum scopes it needs.

Inspecting the current key

const me = await client.apiKeys.whoami();
console.log(me.organizationId, me.scopes);

me = client.api_keys.whoami()
print(me["organizationId"], me["scopes"])

Handling auth errors

Both SDKs raise typed errors for these (CaviusAuthError, CaviusForbiddenError); see the Node.js SDK and Python SDK pages.