Skip to content

ACCOUNT SETTINGS

API Tokens

Create, scope, monitor and revoke the tokens that give external tools, scripts and AI assistants access to your account.

Overview

API tokens let external tools and services work with your Beeswax account: automation platforms such as Zapier and n8n, your own scripts, reporting tools, and AI assistants through the Beeswax MCP server. This page covers managing tokens in the web app. If you are building the thing that will use the token, start at Beeswax API: Overview & Quickstart.

Key characteristics:

  • Account-specific. Each token is tied to a single account and can never see another, even one you also belong to. Bookkeepers create one token per client account.
  • Scope-based. Tokens are granted specific permissions (scopes) that set a ceiling on what they can do. Your own role on the account still applies underneath.
  • Revocable. Tokens can be deactivated at any time without deleting them.
  • Auto-suspended. Tokens stop working while the account's subscription is inactive, and resume when it is active again.
  • Tied to membership. A token works only while the person who created it still belongs to the account. Removing that person revokes their tokens for it at once.
  • Usage tracked. The list shows when each token was last used.

Token management is included with every plan, including Free, and during the trial.

Creating a token

Go to Account Settings → API Tokens, open the ⋯ menu on the API Tokens card and choose Add Token. You will also find the same list under User Settings → API Tokens.

Field Required Description
Name Yes What will use this token, for example "Zapier: new deal → draft invoice" or "Claude Desktop (read only)".
Scopes Yes What the token may do, ticked in a table grouped as Financial, Projects and tasks, Contacts, Time tracking, Calendar and Account. Each kind of record has a View box and, where it can be changed, a Change box whose coloured labels say what it allows (Create, Update, Delete and so on). Ticking Change ticks View too. Select all ticks a whole section, and Full access ticks everything. Tick the fewest that do the job.

Copy the token immediately. The full value is shown once, straight after creation. If you lose it, revoke the token and create another.

Choosing scopes

Each scope is resource:read or resource:write; a write scope includes the matching read, and all grants everything. The full list with what each one unlocks is in API Authentication & Scopes. Rules of thumb:

  • A reporting or sync tool needs :read scopes only.
  • A tool that creates invoices, quotes or bills needs that document's :write plus companies:read, projects:read and transaction_accounts:read to look up clients, projects, accounts and tax codes.
  • A tool that records payments needs payments:write, transaction_accounts:read and the read scope of the documents it settles.
  • Meeting recordings and transcripts use meetings:read; recording meetings and assigning their notes to projects use meetings:write. Calendar events use the separate events:read scope.
  • Reconciliation needs reconciliations:read (and reconciliations:write to tick rows), plus transaction_accounts:read and transactions:read together for the per-account ledger.
  • An AI assistant should get read scopes plus only the specific write scopes you want it to have. See the MCP setup guide.
  • Choose all only when you specifically need the untyped journal reader for payrolls, credit notes and bank transfers.

Using a token

Send it in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

That is the whole of authentication. The base URL, request and response conventions, error codes and rate limits are in Requests, responses & errors, and step-by-step examples are in Recipes. To confirm a token is working, call GET /new_api/v1/meta; it answers any usable token with the account and scopes it carries.

Managing tokens

The list shows each token's name, masked value, scopes, last used, created date and status (Active, Revoked, Expired or No Subscription), and can be filtered by any of them.

Editing. Name and scopes can be changed at any time and take effect on the next request. The token value itself never changes.

Revoking. Deactivates the token immediately; requests using it get a 401. The record stays in the list for audit. Revoke when a token may have leaked or the system using it has been switched off.

Deleting. Removes the token from the list permanently.

Rotating. Create the new token first, update the integration, watch the old token's last used stop moving, then revoke the old one. Keeping both live for the changeover means nothing breaks.

Watching usage. Last used is the health signal for an integration: a live sync keeps it moving, and a stale one has stopped silently. A token that has never been used a month after creation is probably safe to revoke.

Security

  • Treat tokens like passwords. Never commit them to version control, paste them into shared documents or tickets, or put them in browser or mobile code.
  • Least privilege. Grant only the scopes an integration needs, and create separate tokens for separate integrations so one can be revoked without affecting the rest.
  • Revoke temporary tokens when the work ends: a consultant's access, a migration, a trial of a new tool.
  • Never share your Beeswax password with an integration. If a tool asks for your email and password instead of a token, do not use it; a scoped token can be revoked and limited, a password cannot.
  • If a token is exposed, revoke it now. Revocation is instant and affects only that token.
  • Subscription-linked. If the subscription lapses, all tokens are suspended and API access is disabled until it is active again.
  • People who leave lose access at once. Removing someone from the account, or their employment ending in payroll, revokes their tokens for the account immediately, including any that an AI assistant or automation is using. Adding them back later does not revive those tokens; they create new ones. For a long-running integration, create the token as someone who is staying with the account, usually an Owner, so a departure does not switch it off.

Permissions by role

Action Owner Super Admin Manager Accountant Basic Client
Create tokens Yes Yes No No No No
View tokens Yes Yes No No No No
Edit tokens Yes Yes No No No No
Revoke tokens Yes Yes No No No No
Delete tokens Yes Yes No No No No

Basic Plus follows Basic for the actions in this table; its extra access is to account-wide tasks and read-only projects. See Roles.

Only Owners and Super Admins can manage API tokens. Managers, Accountants, Basic users, Contractors and Clients do not see the API Tokens page. A token carries its creator's role: if an Accountant needs an integration that can do something Accountants cannot, an Owner or Super Admin should create the token.

Further reading

← All resources Still have a question? ↗
Browse Topics