> Tillcast is live: the API at https://api.tillcast.com/v1 and the dashboard at https://dashboard.tillcast.com. A key prints on real printers, so do not call the API unless asked. A job carries its receipt as "document", an array of blocks (the recommended way), or as "receiptline", ReceiptLine text, exactly one of the two: read https://docs.tillcast.com/create-a-print-job.md and https://docs.tillcast.com/concepts/documents.md before you write a job body. Do not code against what does not exist yet: webhooks, a template language, stored templates (a job has no template field), OAuth connections and connectors for Make, Zapier and n8n, and OAuth sign-in for the MCP server. SDKs for TypeScript (@tillcast/sdk, version 0.2.0 or later for blocks) and Python (tillcast) exist as pre-1.0 versions. To show a receipt in a web page without printing, there are the npm packages @tillcast/preview and @tillcast/html-render (0.x, no API key, no call to Tillcast to draw): read https://docs.tillcast.com/preview-a-receipt.md. The docs are the source of truth: check the index https://docs.tillcast.com/llms.txt and https://docs.tillcast.com/roadmap.md before you code against anything. For clean Markdown of any page, append .md to the page URL. The Tillcast MCP server is live at https://api.tillcast.com/mcp and takes an API key as a bearer token (setup: https://docs.tillcast.com/connect-an-ai-assistant.md). It acts on the live account and its tools print on real paper, so do not connect to it or call its tools unless the owner asked you to. The MCP server at https://docs.tillcast.com/_mcp/server is a different one: it only searches these docs and cannot call the Tillcast API.

# Authentication and API keys

> How Tillcast API keys work. Every key is restricted, has explicit scopes and is created in the dashboard.

## 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.

```bash wordWrap
curl https://api.tillcast.com/v1/organizations/me \
  -H "Authorization: Bearer $TILLCAST_API_KEY" \
  -H "Tillcast-Version: 2026-10-01"
```

```json wordWrap
{
  "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](/api/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](https://tillcast.com/legal/terms/), 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

| Scope                               | Allows                                                      |
| ----------------------------------- | ----------------------------------------------------------- |
| `customers:read`, `customers:write` | Customers and locations                                     |
| `printers:read`                     | Printers and their status                                   |
| `printers:write`                    | Add, change, move, rotate the secret of and delete printers |
| `jobs:read`                         | Jobs                                                        |
| `jobs:write`                        | Create 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.

#### Printing

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

#### Installer

`printers:write`, `printers:read`, `customers:write`, `customers:read`. For setting up customers, locations and printers. It cannot print or read jobs, so it cannot queue a test page either. See [Provision a venue from your software](/provision-a-venue).

#### Setup and printing

All six scopes. For a first integration: it creates a customer, a location and a printer, and prints on it. Use the Printing preset in production.

#### Read only

All `:read` scopes. For monitoring and reports.

## 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](/concepts/printer-url).
* An organization that is suspended can read and cannot write: a write is `403 organization_suspended`.