Authentication

The Beeving API uses Bearer tokens. Each token belongs to one workspace, and every request made with it is scoped to that workspace's data.

Create a token

1. Log in to app.beeving.com
2. Go to Settings → API Tokens
3. Click New token
4. Give it a name, choose its permissions and, optionally, an expiry date
5. Copy the token. It is shown only once: Beeving stores only a SHA-256 hash of it.

You can also create tokens through the API with POST /api-tokens.

A token is a 48-character alphanumeric string with no prefix.

Use the token

Send it in the Authorization header with every request:

curl https://app.beeving.com/api/v1/workspace \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Permissions

Each route requires one specific permission. Permissions are checked exactly as they are written:

• there are no wildcards;
• write does not imply read.

To create and then read contacts, a token needs both contacts:write and contacts:read.

Permission	Grants
contacts:read	Contacts, companies, deals, tasks and pipeline (read)
contacts:write	Contacts, companies, deals, tasks and pipeline (write)
companies:read / companies:write	CRM companies
contacts:import	POST /contacts/import
contacts:export	GET /contacts/export
lists:read / lists:write	Lists and their members
tags:read / tags:write	Tags and their contacts
segments:read / segments:write	Segments
templates:read / templates:write	Email templates and the marketplace
email_accounts:read / email_accounts:write	Sending accounts (SMTP / OAuth)
campaigns:read / campaigns:write	Campaigns, steps and enrolled contacts
campaigns:send	Start, pause and resume campaigns
analytics:read	Analytics endpoints
webhooks:read / webhooks:write	Webhooks
workspace:read / workspace:write	Workspace, members and invitations
api_tokens:read / api_tokens:write	API tokens
blacklist:read / blacklist:write	Blacklist

GET /api-tokens/permissions returns the up-to-date list.

Least privilege

Create a separate token for each integration, with only the permissions it needs. Give api_tokens:write and workspace:write only to tokens you fully trust: a token holding api_tokens:write can create other tokens.

Expiry and revocation

• A token with an expires_at date stops working after that date.
• To revoke a token immediately, delete it in Settings → API Tokens or call DELETE /api-tokens/{id}.
• last_used_at is updated on every call. Use it to find tokens nobody uses any more.

Authentication errors

Status	message	Cause
401	API token required	The Authorization header is missing
401	Invalid API token	The token is unknown or was revoked
401	API token has expired	expires_at has passed
403	Missing required permission: contacts:write	The token lacks the permission this route requires

{
  "error": "Forbidden",
  "message": "Missing required permission: contacts:write"
}