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 and click Create New 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 The permissions the token carries. Grouped as Financial, Companies, Projects & Tasks, Time Tracking, Calendar, Account and Full Access. Tick the fewest that do the job.
Expires at No A date after which the token stops working. Set one for anything temporary.

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.
  • 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, scopes and expiry 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.
  • Set expiry dates on anything temporary: 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

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

Browse Topics