API keys explained: Print bridge, Printing and Full accessHome & Business

An API key lets another program use your Laberty account. That program might be the print bridge on your network, or an app you or someone else wrote. Make keys on Admin → API keys, one per program, so you can switch one off without breaking the others.

A key looks like lbk_ followed by 40 characters. Programs send it with every request:

Authorization: Bearer lbk_...

The three kinds of key

Every key has a scope, and the scope decides what it may call. A scope only ever narrows access. A key can never do more than your plan allows.

Print bridge

For the print bridge on your network, and nothing else. You don't have to make this one yourself: Admin → Print bridge → Download your bridge makes a new one for every download, named like Bridge download 2026-09-26 (Windows), and puts it inside the ZIP. Revoke the one for a lost ZIP here.

• Can: pick up print jobs and report whether they printed. These are the /api/agent/… calls.
• Can't: list printers, send print jobs, see households, or call anything else.
• Plans: Home and Business.
• If it leaks: someone could pick up your queued print jobs, and labels can carry names and addresses. Revoke it and make another.

Printing

For your own apps that print: a point-of-sale, an inventory or shipping app, a script.

• Can:
  • GET /api/printers: list printers, their type, and what's loaded in each
  • POST /api/print: send a job
  • GET /api/print and GET /api/print/{id}: recent jobs, and whether a job printed
  • GET /api/agent/status: whether the bridge is running
• Can't: read or add households, list label sizes (/api/label-stock), email label batches, change what's loaded in a printer, or act as a bridge.
• Plans: Home (20 API actions a month) and Business (unlimited).

Full access

For programs you trust with everything the API can do.

• Can: everything a Printing key can, plus:
  • GET and POST /api/households: read and add households
  • GET /api/label-stock: list your label sizes
  • POST /api/print/email: email a batch of address labels to the member
  • POST /api/printers/{id}/loaded-stock: tell Laberty a roll was swapped
  • the bridge calls
• Plans: Home (20 API actions a month) and Business (unlimited).

Which one should I pick?

Pick the smallest scope that does the job. If a key ever leaks, it can only do what its scope allows.

Rules every key follows

• Shown once. Laberty keeps only a scrambled fingerprint of the key (a SHA-256 hash), never the key itself. Copy it when it's made. If you lose it, revoke it and make another.
• Never expires. A key that quietly expires inside another app is an outage nobody sees coming. Access ends only when you revoke the key.
• Revoke any time. Press Revoke next to the key. It stops working on its very next request. Your other keys aren't affected.
• Named. Name each key after its program, like "Front counter POS" or "Garage bridge". The list shows when each key was made and last used, and print jobs record which key sent them.
• Secret. Treat a key like a password. Keep it on your server, out of web pages, downloadable apps, screenshots and git.

How many keys each plan includes

Revoked keys don't count. At Home's limit, Laberty tells you when you try to make another; revoke one you no longer use. Business has no plan limit, only a ceiling of 200 live keys to stop a runaway script making keys in a loop.

API actions. Home includes 20 API actions a month; Business is unlimited. An action is a call that does something, like sending a print job or adding a household. Reading (listing printers, checking whether a job printed) is free, and the print bridge never counts. The count is shared by all of the account's keys and shows on Admin → API keys. See Limits.

What a refusal looks like

• 401 Unauthorized: the key is missing, mistyped or revoked.
• 403 Forbidden, with a message saying why:
  • Wrong kind of key: This is a "Printing" key, which cannot call /api/households. Make a key that covers it under Admin → API keys.
  • Plan: The API needs a paid plan…, or for bridge calls, The print bridge needs a paid plan.
• 429 Too Many Requests with "code": "api_quota": Home's 20 API actions for the month are used up. Reads still work, and the allowance comes back on the 1st (resetsAt says exactly when).

If your plan changes, for example back to Free, your keys stay in the list but their calls are refused until the plan allows them again.

Older setups may use a single account-wide token instead of keys. It still works, but it can do everything and can't be revoked without breaking everything that uses it. Move each program to its own key.