API and webhooks

Create an API token

1. Open Settings → API tokens.
2. Type a name for the token (e.g. “SIS sync”), click Create, and copy the token. It’s shown once, so store it in your secrets manager.
3. Tokens are scoped to your organization. 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 tokens → View docs (signed-in admins only).

• GET /api/v1/employees: list all your employees.
• POST /api/v1/employees: create or update up to 1,000 employees per request, matched on employee_id. Fields you leave out keep their current values.
• GET /api/v1/templates: list your templates (name, card size, and whether each one is two-sided).
• GET /api/v1/print-jobs: list recent print jobs, newest first.

Employee rows include a photo_id, not the photo itself. The API doesn’t return photo files or rendered badges.

Webhooks

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

• badge.printed: every printed card, whether it came from an employee’s Print button, a bulk print, or the kiosk. Carries the badge, employee, template, and operator IDs.
• badge.created: the first time an employee’s badge prints on a template.
• print_job.created: once per print run, with the badge IDs and the number of cards in it.
• employee.created, employee.updated, employee.terminated: when employees are added, edited, or terminated, by hand, through a CSV import, or through the API. Each carries the employee’s internal ID and their employee number.

Deliveries are sent once, with a five-second timeout, and aren’t retried automatically. Each endpoint’s recent deliveries show the result, and you can replay any of them.

Every delivery includes an x-badgebadger-signature: sha256=<hex>header: an HMAC-SHA256 of the raw request body, keyed with the endpoint’s signing secret (BadgeBadger generates it when you create the webhook). Verify it before trusting the payload. It’s the same scheme GitHub uses for its webhooks. The full reference has example code.

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.