Authentication and API keys
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.
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
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.
Printing
Installer
Setup and printing
Read only
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.
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
Authorizationheader 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.