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.

LevelScopes
Full access (read, write, send messages)read write messages:send
Read onlyread
Read + send messagesread 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.

ScopeWhat it allowsEndpoints
readCore reads: bot list, contacts, conversations, messages, campaigns, Mini Apps, automations, webhooks, templates, usage14
writeCore writes: contacts, consent, conversation status, creating campaigns, orders, turning automations on or off, webhooks10
messages:sendSend messages to customers2
bots:readBot settings, knowledge sources, tools, versions, evaluations, acquisition links24
bots:writeCreate, update, connect and delete bots, and manage AI knowledge42
automations:readAutomation details and run history2
miniapps:readRead Mini Apps, versions, orders and custom requests7
contacts:readExport contacts, read tags and custom fields3
conversations:readConversation details, internal notes, saved replies4
campaigns:readCampaign results, audience counts, best send time6
communities:readRead communities, invite links and scheduled posts6
reports:readOverview, delivery, agent, satisfaction, AI quality, revenue and usage reports8
organization:readOrganization settings, content policy, AI settings, stores, media, audit log, billing10
team:readTeam members and pending invitations2
webhooks:readWebhook details and delivery history2
api_keys:readList API keys and connected apps3
automations:writeCreate, save and delete automations3
miniapps:writeMini App drafts, publishing, rollback and custom requests14
contacts:writeAdd, delete, import and bulk-edit contacts; manage tags and custom fields14
conversations:writeAssign, snooze, mark read, internal notes, saved replies and message retries12
campaigns:writeUpdate and delete campaigns that haven't started, campaign costs; approval still can't be given9
communities:writeManage communities, invite links and scheduled posts12
organization:writeChange organization, content policy, AI, stores and media11
team:writeInvitations, roles, bot access and removing members4
webhooks:writeUpdate webhooks and send test events2
api_keys:writeRevoke API keys and remove connected apps2

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.
ActionMemberAdminOwner
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 a client_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). If scope is empty, only read is granted.
Server metadata
curl "https://hiboty.com/.well-known/oauth-authorization-server"
Client registration
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"]}'
Authorization address
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=S256
Exchanging the code for tokens
curl -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_VERIFIER
Using the token
curl "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.