Overview

API tokens authenticate your code against the Beeswax STP JSON API. They come in two flavours — test (for EVTE sandbox) and live (for production ATO) — and are managed from Settings → API Tokens.

This page covers the web UI for managing tokens. For how to actually use them in code, see:

Creating a token

On the API Tokens page:

  1. Choose the environment — Test or Live

    • Test tokens (prefix stp_test_...) talk to the ATO's EVTE sandbox via employers with environment: "evte". Safe for development, CI, staging.
    • Live tokens (prefix stp_live_...) trigger real ATO lodgements via employers with environment: "production". Treat them like production passwords.

  2. Name the token — a label to identify what this token is used for, e.g. "Beeswax production", "Staging CI", "Aria's laptop".

  3. Set an expiry date (optional) — the token will stop working after this date. Useful for short-lived integrations or mandatory rotation.

  4. Choose scopes — the minimum set of capabilities this token needs. Granular scopes reduce blast radius if a token is leaked. See the Authentication guide for the full list.

  5. Generate token — the full token value is shown once. Copy it immediately; we only keep a hash, so if you lose it you'll need to revoke and regenerate.

Environment isolation

This is the most important thing to understand about tokens:

A test token can never affect production data. A live token can never see test data.

This isolation is enforced at the database query layer, not just the UI. It's designed to be impossible to accidentally submit real pay events from a CI script that's meant to run against the sandbox.

Practical implications:

  • Test and live employers are completely separate — data doesn't cross over
  • If you create an employer with environment: "evte" while holding a live token, the employer will be created but invisible to the API (use the UI to see both)
  • Webhooks are also environment-scoped — see Webhooks

Managing existing tokens

The token list is split into Test and Live tabs. Each token shows:

  • The name
  • A masked preview of the token (stp_test_…abc4)
  • Last used timestamp
  • Expiry (if set)
  • Scopes

Revoking a token

Click Revoke next to any token. Revocation is immediate — the next request using the token returns 401 Unauthorized. Revoked tokens remain in the audit log but are hidden from the active view.

Rotating a token

To rotate a live token without downtime:

  1. Create a new token with the same scopes
  2. Deploy the new token to your servers
  3. Verify it's working (check last_used_at in the UI)
  4. Revoke the old token

The new token must match the environment of the old one — you can't rotate a test token to a live token mid-deployment.

Scopes

Tokens can be scoped to limit what they can do. See Authentication → Scopes for the full table.

Recommended patterns:

  • Production integration: everything you need (typically all :read and :write scopes except submissions:write)
  • CI / testing script: test environment, read-only scopes
  • Reporting / dashboard: employers:read, employees:read, pay_events:read, ytd:read
  • Webhook receiver: no API token needed — webhooks are server-to-you-only

Security best practices

  1. Treat tokens like passwords. Never commit them to git, even in test files. Use environment variables or a secrets manager.
  2. Scope tightly. A read-only report tool shouldn't have write access.
  3. Use test tokens for development. If a test token leaks, the blast radius is the sandbox — no real data affected.
  4. Rotate regularly. Annual rotation for production tokens is a reasonable baseline. Rotate immediately on suspected compromise.
  5. Monitor last_used_at. Revoke dormant tokens.
  6. Set expiry on temporary tokens. Contractors, migrations, debugging sessions — all good candidates.
  7. Never log tokens. Redact Authorization headers in your application logs.
  8. HTTPS only. We reject HTTP at the proxy layer.

Audit trail

Every token creation, revocation, and use is recorded in the Audit log. If a token is compromised, you can see exactly which requests it made and when — helpful for incident response.