Skip to navigation

Authentication and API keys

Restricted keys with scopes, how they are created and how to use them.
View as Markdown

Send the key

Send a key as a bearer token in the Authorization header. GET /v1/organizations/me is a good first call: any valid key may call it, and it answers with your organization, the key’s own details and how many customers, locations and printers the key can see.

curl https://api.tillcast.com/v1/organizations/me \
-H "Authorization: Bearer $TILLCAST_API_KEY" \
-H "Tillcast-Version: 2026-10-01"
{
"object": "organization",
"id": "org_01M3ZYPDG0T1Y4B7N0M3Q6S9VD",
"name": "Example Hotels AB",
"state": "active",
"customers": 1,
"locations": 1,
"printers": 1,
"api_key": {
"id": "key_01M3ZYPDZ0M9P2R5T8V1X4Z7B0",
"label": "production",
"last4": "8fqz",
"scopes": ["jobs:read", "jobs:write", "printers:read"],
"customer": null,
"expires_at": null
}
}

A key looks like tc_rk_live_ followed by 32 characters. The prefix makes a leaked key easy to spot in logs and code. The Tillcast-Version header is optional. See Versioning.

Every key is a live key and prints on real printers. An organization can use a free trial on real printers, one per organization and per person: 1 month, 250 printed jobs in total, no card to start (terms of service, section 8a).

A request with no key is 401 authentication_required. A key that is wrong, revoked or expired is 401 invalid_api_key, and so is a string that is not shaped like a key, which is refused before anything is looked up. A key without the scope for a call is 403 insufficient_scope.

Restricted keys only

Every key is a restricted key. There is no full-access key.

  • A key lists its permissions, called scopes, explicitly. A preset expands to explicit scopes when the key is created, so a key never gains scopes later.
  • A key covers the whole organization, or only one customer. A key limited to one customer sees and changes only that customer. Use it for a customer’s own system. It cannot create customers (403 restricted_key) and it cannot suspend or delete one.
  • A key can never create or change keys, so it cannot grant more than it has.
  • The organization and the customer a call acts for come from the key and never from the request.

Scopes

ScopeAllows
customers:read, customers:writeCustomers and locations
printers:readPrinters and their status
printers:writeAdd, change, move, rotate the secret of and delete printers
jobs:readJobs
jobs:writeCreate and cancel jobs, and queue a test print

Scopes for events, webhooks, usage statistics, the audit log and raw printer commands are planned with the features that need them. They are not accepted yet.

Presets

The dashboard offers these presets when you create a key. You can also pick the scopes yourself.

jobs:write, jobs:read, printers:read. For a point-of-sale or property management integration that sends receipts.

How keys are created

Keys are created in the dashboard at dashboard.tillcast.com, under API keys, by a person who is signed in. They cannot be created through the API.

  • Anyone can create an organization in the dashboard, and it is active at once, so its owner can create keys from the first minute.
  • Only the roles owner and developer can create keys. A viewer can read.
  • Creating a key needs an extra confirmation, beyond signing in: a six-digit code that Tillcast e-mails to your confirmed address.
  • The dialog asks for a label, a preset, the scopes, whether the key works for the whole organization or one customer, and an expiry: never, in 30, 90 or 365 days, or on a date.
  • The key is shown once. Tillcast keeps only a hash of it, and the list shows only its last four characters.
  • A key can be renamed, duplicated and revoked. A revoked key stops working within a minute.
Rotate without downtime

Use two keys per integration. Create the new key, deploy it, then revoke the old one.

Keep keys safe

  • Never put a key in a browser, a mobile app, source code or a log. The API accepts calls from a browser only for the dashboard, so a key in a web page would not even work. Call the API from your server.
  • Keep the key in an environment variable or a secret store, for example TILLCAST_API_KEY.
  • Tillcast never writes keys or the Authorization header to its logs.
  • A printer URL is a different credential. See Printer URL.
  • An organization that is suspended can read and cannot write: a write is 403 organization_suspended.