Overview
API tokens let you connect external tools and services to your Beeswax account. Each token is linked to a specific user and account, and all API calls using that token operate in the context of that account.
Key characteristics:
- Account-specific — Each token is tied to a single account. This is useful for bookkeepers managing multiple client accounts.
- Scope-based — Tokens are granted specific permissions (scopes) that control what they can access.
- Revocable — Tokens can be deactivated at any time without deleting them.
- Auto-revoked — Tokens are automatically invalidated when the account's subscription becomes inactive.
- Usage tracked — The system records when each token was last used.
Creating a Token
Navigate to Account Settings > API Tokens to manage your tokens.
Fields
| Field | Required | Description |
|---|---|---|
| Name | Yes | A descriptive label to identify what this token is used for. |
| Scopes | Yes | The permissions granted to this token. |
| Expires At | No | An optional expiration date. The token stops working after this date. |
Important
The full token value is only shown once — immediately after creation. Copy it and store it securely. You will not be able to view the full token again.
Available Scopes
Scopes control what actions a token can perform via the API.
| Scope | Description |
|---|---|
| companies:read | View companies |
| companies:write | Create and update companies |
| expenses:read | View expenses |
| expenses:write | Create and update expenses |
| invoices:read | View invoices |
| invoices:write | Create and update invoices |
| quotes:read | View quotes |
| quotes:write | Create and update quotes |
| payments:read | View payments |
| transactions:read | View ledger transactions (line items / postings) |
| journal_entries:read | View manual / general journal entries |
| journal_entries:write | Create, post and delete manual (general) journal entries |
| tax_returns:read | View tax returns |
| tax_returns:write | Update tax return figures and confirm sections |
| projects:read | View projects |
| projects:write | Create and update projects |
| tasks:read | View tasks |
| tasks:write | Create and update tasks |
| time_entries:read | View time entries |
| time_entries:write | Log time entries |
| milestones:read | View milestones |
| transaction_templates:read | View products & services |
| events:read | View calendar events |
| users:read | View users |
| accounts:read | View account information |
| all | Full access to all API endpoints |
Scopes are grouped in the token form so you can choose financial, company, project/task, time tracking, calendar, account, or full-access permissions. A read scope is also satisfied by the matching :write scope or by all — an invoices:write token can read invoices.
Authentication
Include your API token in the Authorization header of your HTTP requests:
Authorization: Bearer YOUR_API_TOKEN
The current JSON API expects the Bearer token header. Query-string tokens are not used for API token authentication.
Available API Endpoints
| Endpoint | Method | Description | Required Scope |
|---|---|---|---|
| /new_api/v1/accounts | GET | List accounts available to the token user | accounts:read or all |
| /new_api/v1/accounts/switch | POST | Switch the token context to another account | all |
| /new_api/v1/active_account/projects | GET | List active-account projects | projects:read |
| /new_api/v1/active_account/projects/:id | GET | View a single project | projects:read |
| /new_api/v1/active_account/projects/:project_id/milestones | GET | List a project's milestones | milestones:read |
| /new_api/v1/active_account/users | GET | List users in the token's account | users:read |
| /new_api/v1/invoices, /invoices/:id, /invoices/:id/transactions | GET | List / view invoices and their ledger postings | invoices:read (transactions also accept transactions:read) |
| /new_api/v1/quotes, /quotes/:id, /quotes/:id/transactions | GET | List / view quotes and their postings | quotes:read |
| /new_api/v1/expenses, /expenses/:id, /expenses/:id/transactions | GET | List / view expenses and their postings | expenses:read |
| /new_api/v1/payments, /payments/:id, /payments/:id/transactions | GET | List / view payments and what each one applies to | payments:read |
| /new_api/v1/journal_entries, /journal_entries/:id, /journal_entries/:id/transactions | GET | Generic ledger reader; filter with ?type=invoices etc. | the matching type's read scope; all for a bare list, a single entry, or long-tail types (payrolls, credits, bank_transfers) |
| /new_api/v1/time_entries, /time_entries/:id | GET | List / view time entries | time_entries:read |
| /new_api/v1/events, /events/:id | GET | List / view calendar events (only those visible to the token's user) | events:read |
| /new_api/v1/milestones, /milestones/:id | GET | List / view milestones | milestones:read |
| /new_api/v1/transaction_templates, /transaction_templates/:id | GET | List / view products & services (filter by kind=product/service, active, query) | transaction_templates:read |
| /new_api/v1/raw_journal_entries, /raw_journal_entries/:id | GET/POST/DELETE | List, view, create (balanced debits & credits, posted immediately or as a draft) and delete draft manual journals | journal_entries:read / journal_entries:write |
| /new_api/v1/raw_journal_entries/:id/finalise | POST | Post a draft manual journal to the ledger | journal_entries:write |
| /new_api/v1/tax_returns, /tax_returns/:id, /tax_returns/:id/findings | GET | List / view tax returns and their AI review findings (Australian accounts) | tax_returns:read |
| /new_api/v1/tax_returns/:id/sections/:section_key/fields/:field_key/transactions | GET | Ledger transactions behind a tax-return field | tax_returns:read |
| /new_api/v1/tax_returns/:id/field | PATCH | Override a tax-return field value (blank clears the override) | tax_returns:write |
| /new_api/v1/tax_returns/:id/sections/:section_key/confirm | POST | Confirm (sign off) a tax-return section | tax_returns:write |
| /new_api/v1/tasks | GET/POST | List or create tasks (plus comments, files, timers and state transitions under /tasks/:id/...) | tasks:read / tasks:write |
| /new_api/v1/users/me | GET | The token's user and their default project | any usable token (deliberately unscoped — token introspection) |
| /new_api/v1/invoice_uploads | GET/POST | Review or upload expense/invoice files for processing | expenses:read / expenses:write (needs the expenses plan feature) |
| /new_api/v1/expenses/uncategorized | GET | View uploaded expenses awaiting review (admins see all; others see their own uploads) | expenses:read (needs the expenses plan feature) |
| /new_api/v1/expenses/processed | GET | View expenses already reviewed out of the inbox | expenses:read (needs the expenses plan feature) |
| /new_api/v1/expenses/uncategorized/:id/assign | POST | Assign an uploaded expense to operating costs or a project | expenses:write (needs the expenses plan feature) |
The invoices, quotes, expenses, payments, journal_entries, time_entries, events, milestones, and transaction_templates (products & services) endpoints are currently read-only (list + view) — writes for those document types are planned for a future release. Manual journals (
raw_journal_entries) and tax-return fields are writable today with the matching:writescope. List endpoints acceptpageandper_page(max 100) and return ametablock plusX-Total-Count/X-Total-Pagesresponse headers.
Integration Examples
Zapier
- Choose Webhooks by Zapier as your action.
- Set the URL to
https://app.beeswaxapp.com/new_api/v1/[endpoint]. - Add a custom header:
Authorization: Bearer YOUR_API_TOKEN. - Set the request type to POST.
- Configure the JSON body with the required fields.
N8n
- Add an HTTP Request node.
- Set the method to POST.
- Set the URL to
https://app.beeswaxapp.com/new_api/v1/[endpoint]. - Under Authentication, select Generic Credential Type and choose Header Auth.
- Set the header name to
Authorizationand value toBearer YOUR_API_TOKEN.
Managing Tokens
Editing
You can update a token's name, scopes, and expiration date. The token value itself cannot be changed — use regenerate to create a new value.
Revoking
Revoking a token deactivates it immediately. Revoked tokens can no longer authenticate API requests. The token record is kept for audit purposes.
Deleting
Deleting a token removes it permanently from the system.
Security
- Never share tokens publicly — Treat API tokens like passwords. Do not commit them to version control or include them in client-side code.
- Use scopes wisely — Grant only the minimum permissions needed for each integration.
- Set expiration dates — For temporary integrations, set an expiration date so the token automatically stops working.
- Monitor usage — Check the "last used" timestamp to identify unused or potentially compromised tokens.
- Subscription-linked — If your subscription lapses, all tokens are automatically revoked and API access is disabled.
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 |
Key Notes
- Only Owners and Super Admins can manage API tokens.
- Managers, Accountants, Basic users, Contractors, and Clients cannot access API token management.
- API token management is included with every plan — including the Free plan — and during the trial.