Developers
Authentication and scopes
Connect with an API key or an OAuth access token; scopes and the key creator's role together decide what you can do.
API keys
Every request carries an Authorization: Bearer <api_key> header. Keys start with the hb_live_ prefix, are created in the dashboard under Settings → API, are shown only once at creation and are stored hashed on the server. A missing or revoked key returns 401 unauthorized.
- Don't put the key in client-side code, the browser or a repository; keep it in an environment variable on the server.
- Revoke a key you think has leaked, in the dashboard or with
revokeApiKey; it stops working immediately. - New keys are created only in the dashboard, by a user with a verified email: a key minting wider keys would be a security hole.
Take care when handing out a key or permission that can message your customers. Values such as hb_live_YOUR_API_KEY in the samples are placeholders.
Access levels
You choose a level when creating a key in the dashboard; each level maps to the scopes below. Grant only what the integration needs.
| Level | Scopes |
|---|---|
| Full access (read, write, send messages) | read write messages:send |
| Read only | read |
| Read + send messages | read messages:send |
| Full access + bot management (bots:read, bots:write) | read write messages:send bots:read bots:write |
| Read only + read bot settings (bots:read) | read bots:read |
| Full management (every scope: automations, Mini Apps, contacts, conversations, campaigns, communities, reports, organization, team, webhooks, keys) | All scopes (26) |
| Full read (read every resource, no writes) | read bots:read automations:read miniapps:read contacts:read conversations:read campaigns:read communities:read reports:read organization:read team:read webhooks:read api_keys:read |
All scopes
A request outside the key's scopes returns 403 scope. read and write exist on older keys too; resource scopes (such as contacts:read) are separate, so older keys never gain access by themselves. Each endpoint's scope is listed in the API reference.
| Scope | What it allows | Endpoints |
|---|---|---|
read | Core reads: bot list, contacts, conversations, messages, campaigns, Mini Apps, automations, webhooks, templates, usage | 14 |
write | Core writes: contacts, consent, conversation status, creating campaigns, orders, turning automations on or off, webhooks | 10 |
messages:send | Send messages to customers | 2 |
bots:read | Bot settings, knowledge sources, tools, versions, evaluations, acquisition links | 24 |
bots:write | Create, update, connect and delete bots, and manage AI knowledge | 42 |
automations:read | Automation details and run history | 2 |
miniapps:read | Read Mini Apps, versions, orders and custom requests | 7 |
contacts:read | Export contacts, read tags and custom fields | 3 |
conversations:read | Conversation details, internal notes, saved replies | 4 |
campaigns:read | Campaign results, audience counts, best send time | 6 |
communities:read | Read communities, invite links and scheduled posts | 6 |
reports:read | Overview, delivery, agent, satisfaction, AI quality, revenue and usage reports | 8 |
organization:read | Organization settings, content policy, AI settings, stores, media, audit log, billing | 10 |
team:read | Team members and pending invitations | 2 |
webhooks:read | Webhook details and delivery history | 2 |
api_keys:read | List API keys and connected apps | 3 |
automations:write | Create, save and delete automations | 3 |
miniapps:write | Mini App drafts, publishing, rollback and custom requests | 14 |
contacts:write | Add, delete, import and bulk-edit contacts; manage tags and custom fields | 14 |
conversations:write | Assign, snooze, mark read, internal notes, saved replies and message retries | 12 |
campaigns:write | Update and delete campaigns that haven't started, campaign costs; approval still can't be given | 9 |
communities:write | Manage communities, invite links and scheduled posts | 12 |
organization:write | Change organization, content policy, AI, stores and media | 11 |
team:write | Invitations, roles, bot access and removing members | 4 |
webhooks:write | Update webhooks and send test events | 2 |
api_keys:write | Revoke API keys and remove connected apps | 2 |
Role behavior
Even with the right scope, an action needs the same role in the API as in the dashboard; otherwise you get 403 forbidden_role.
- An API key works with the current role of the person who created it: if their role changes, so does the key's access.
- If the creator leaves the team the key works like an admin; owner-only actions stay closed. We recommend revoking it and creating a new one.
- The member role only sees data of bots it can access; a record it can't access returns
404. - An OAuth token works with the current membership of the user who granted it; if that user leaves the team you get
403 forbidden_role.
| Action | Member | Admin | Owner |
|---|---|---|---|
| Reads, messages and conversation actions (on accessible bots) | ✓ | ✓ | ✓ |
| Bot settings, contact management, campaigns, automations, Mini Apps, webhooks | — | ✓ | ✓ |
| Changing a member's role | — | — | ✓ |
Deleting a bot (deleteBot) | — | — | ✓ |
Each endpoint's role requirement is in its description in the reference. The check on the endpoint is the final rule.
OAuth 2.1
For apps and MCP clients a user authorizes with their own account. It uses the authorization code flow with PKCE (S256); client registration is dynamic and there is no client secret.
- Read the server metadata.
- Register your client (
/oauth/register) to get aclient_id. The redirect address must be https or local http. - Send the user to the authorization page with PKCE. They sign in, choose an organization and allow access.
- Exchange the returned code for tokens (
/oauth/token). Ifscopeis empty, onlyreadis granted.
curl "https://hiboty.com/.well-known/oauth-authorization-server"curl -X POST "https://hiboty.com/oauth/register" \
-H "Content-Type: application/json" \
-d '{"client_name":"My App","redirect_uris":["https://ornek.com/oauth/callback"]}'https://hiboty.com/oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fornek.com%2Foauth%2Fcallback&scope=read%20messages%3Asend&state=RANDOM_STATE&code_challenge=PKCE_S256_CHALLENGE&code_challenge_method=S256curl -X POST "https://hiboty.com/oauth/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d grant_type=authorization_code \
-d code=AUTHORIZATION_CODE \
-d client_id=CLIENT_ID \
-d redirect_uri=https://ornek.com/oauth/callback \
-d code_verifier=PKCE_VERIFIERcurl "https://hiboty.com/api/v1/bots" -H "Authorization: Bearer hb_oat_YOUR_ACCESS_TOKEN"Access tokens start with hb_oat_, are valid for 60 minutes and use the same header as API keys. Refresh tokens start with hb_ort_ and are valid for 90 days; refresh with grant_type=refresh_token. You can revoke tokens with /oauth/revoke; connected apps appear in the dashboard under Settings → API and through listConnectedApps.