API and webhooks

Create an API token

1. Open Settings → API.
2. Click New token, give it a label (e.g. “Workday sync”), and copy the token. It’s shown once — store it in your secrets manager.
3. Tokens are scoped to your organisation. Revoking a token from the same page invalidates it immediately.

Endpoints

All endpoints accept Authorization: Bearer <token> and return JSON. See the full reference at Settings → API → Docs (signed-in users only).

• GET /api/v1/employees — list, with pagination.
• POST /api/v1/employees — create or upsert by employee_id.
• GET /api/v1/templates — list of available templates (mirrors what the editor shows).
• POST /api/v1/print-jobs — queue a print server-side (rather than via a browser). Targets a paired Print Agent by hostname or label.

Webhooks

From Settings → Webhooks, register HTTPS URLs to receive events:

• badge.printed — fires every time a card prints (operator, employee, template, agent device).
• employee.created / employee.updated / employee.terminated.
• template.printed_first_time— useful for “the design has been locked” downstream automation.

Every webhook delivery includes an X-Badgebadger-Signature header (HMAC-SHA256 over the body, keyed with a secret you set per endpoint). Verify it before trusting the payload — the same signing scheme that Stripe and GitHub use.

Replay + rotate

The webhooks tester at Settings → Webhooks → Recent deliveries lets you replay any past delivery (handy when a receiver was down) and rotate the signing secret on demand.