Authentication & API keys

You sign in to the dashboard with your account. To call the HTTP API from your backend, you use an API key. There are two kinds of keys; keep them straight.

Account API keys

An account API key authenticates calls to the HTTP API (api/v1). Pass it as a Bearer token on every request:

Authorization: Bearer hania_sk_3f9a8c21d4e7b05f6a1c9e2d8b7401fa5c3e9d2b

Keys are prefixed hania_sk_. An account key is a full-tenant credential meant for your server - never put it in client-side code (the API is server-to-server and rejects cross-origin browser calls).

Create a key

In the dashboard, go to Settings → API keys → Create key. Give it a name, select the abilities it needs, and optionally set an expiry date and an hourly rate limit. The full secret is shown once at creation, so copy it into a secret manager; you won't be able to see it again. Revoke a key any time from the same page, and any client using it loses access immediately.

Abilities

Each key carries a set of abilities that scope what it can do, for example bots:read to list bots, or chat:send to message a bot. Read endpoints require the resource's :read ability; create/update/delete require :write. You can also grant wildcards (* for everything, or bots:* for a whole resource). Grant only what each integration needs. The full catalog and the per-endpoint mapping are in the API overview.

A key can never do more than the person who made it. If your workspace role is Member, the abilities on your key are trimmed to match your own, and asking for * is refused with a message naming what was turned down. Members also see only the keys they created; owners and admins see every key in the workspace. Viewers can't create keys at all.

Widget keys (public)

A widget key is different: it's the public, domain-restricted key for the embeddable chat widget that runs in the browser. Widget keys use a hania_ prefix (no sk_) and are designed to be visible in client-side HTML. You create and manage them per bot. See Widgets.

Auth errors

A missing or invalid key returns 401 (intentionally generic). A valid key that lacks the needed ability returns 403 with "Missing ability: <name>". See Errors for the full list.