Overview

API Tokens allow external systems (like Beeswax or other payroll software) to submit pay data to Beeswax STP via the JSON API. Each token can be scoped to specific operations and has optional expiry.

Creating a Token

To create a new API token:

  1. Enter a Token Name — a label to identify what this token is used for (e.g., "Beeswax Production")
  2. Set an Expiry Date (optional) — the token will stop working after this date
  3. Select Scopes — which API operations the token can perform

Available Scopes

Scope Description
employers:read View employer details
employers:write Create and update employers
employees:read View employee details
employees:write Create and update employees
pay_events:read View pay events
pay_events:write Create, update, and submit pay events
submissions:read View submission history
ytd:read View YTD summary data
  1. Click Generate Token

The token will be displayed once only. Copy it immediately and store it securely — it cannot be retrieved again.

Using the API

Authentication

Include the token in the Authorization header of every API request:

Authorization: Bearer <your-token>

Base URL

All API endpoints are under /api/v1/.

Key Endpoints

  • GET /api/v1/employers — list employers
  • POST /api/v1/employers — create an employer
  • GET /api/v1/employers/:id/employees — list employees
  • POST /api/v1/employers/:id/employees — create an employee
  • POST /api/v1/pay_events — create a pay event
  • POST /api/v1/pay_events/:id/items — add an employee pay item
  • POST /api/v1/pay_events/:id/mark_ready — mark pay event as ready
  • POST /api/v1/pay_events/:id/submit — submit to the ATO

Pagination

List endpoints return paginated results with headers:

  • X-Total-Count — total number of records
  • X-Page — current page number
  • X-Per-Page — records per page
  • X-Total-Pages — total pages available

Managing Tokens

Active Tokens

The token list shows all active tokens with:

  • Token name and a masked preview of the token value
  • Last used timestamp
  • Expiry date (if set)
  • Assigned scopes

Revoking Tokens

Click Revoke to immediately deactivate a token. Any systems using the revoked token will lose API access. Revoked tokens appear in a separate section below active tokens.

Security Notes

  • Tokens are generated using cryptographically secure random values
  • Store tokens securely — treat them like passwords
  • Use the minimum scopes necessary for each integration
  • Set expiry dates for tokens used in temporary integrations
  • All API actions are recorded in the Audit Log
  • Revoke tokens immediately if they may have been compromised