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 — 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.

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.