Printer URL
Printer URL format
Each printer gets one URL. The values below are made up.
- You enter it in one field of the printer’s settings: the Server URL of a Star printer, or the URL of the Server1 setting of an Epson. See Set up a Star printer and Set up an Epson printer.
- There is no username and no password. The secret in the URL is the credential. Leave the username and password fields of the printer empty.
- The URL is
httpsonly. Tillcast listens on no plain HTTP port, so a printer set tohttp://fails to connect before it sends anything. - The URL has no trailing slash. A path with more than one part, a trailing slash or a dot is not a printer URL.
You get the URL when you add the printer, in the dashboard or in the answer of the API. See the Quickstart.
The two parts of the URL
Both parts use only the digits 2 to 9 and the lowercase letters except i, l and o, so no character can be read two ways. Upper and lower case are treated the same.
The last character of each part is a check symbol. A typo in a single character, or a swap of two neighbouring characters, makes the check fail, and Tillcast rejects the request without looking anything up. See Troubleshooting.
The customer code is not secret. It appears in DNS and in the host name, and it grants nothing without the secret. The id of the customer in the API is cus_ and the code.
Treat the URL as a password
The secret is the only credential a printer has. Anyone who has the whole URL can poll as that printer, download the receipts waiting for it and confirm them.
- Tillcast keeps only a hash of the secret. The full URL is shown once: when the printer is added, when its secret is rotated, and when a move to another customer changes its host. A replayed request that added the printer answers
url: null. - If the URL is lost or leaks, rotate the secret with
POST /v1/printers/{printer}/rotate-secret, which needs theprinters:writescope. The answer holds the new URL, and the old URL stops working at once. In the dashboard, an owner or a developer presses Rotate secret on the printer’s page, and the new URL is shown once. - Do not put the URL in logs, tickets, chat messages or source code. Tillcast never writes it to its own logs: the path of a request is logged only as
/<secret>. - The printer’s own web page shows the URL. Change the printer’s web admin password if it is still the factory default. See Set up a Star printer.
Check a URL in a browser
Open the printer URL in a browser on the same network. You get a small page, not a receipt. It checks the form of both parts and says one of these:
- The form of the URL is right. The page cannot tell whether the secret exists, so it cannot be used to test guesses. If the printer still does not connect, compare the URL with the one you were given.
- There is a typo in the customer code, or in the secret.
- The URL is not active.
- The address has no secret after the host.
The page also has a box where you can type a URL to check its symbols. It does this in your browser, with no request.
Allow only one device (optional)
By default any device that holds the URL works, and nothing ties the URL to the first device that connects. A printer can name the one device that is allowed to use it, by its MAC address, in the field allowed_mac. In the dashboard it is the optional Allowed device (MAC address) field of the Edit printer dialog, and of the Add printer dialog under Advanced once a maker is chosen there. A printer added by its paper width takes an allowed device only after it has connected and its maker is known.
This is a safeguard for one address and not authentication. A MAC address is printed on the label of the printer, and its first three bytes name the maker. The secret in the URL stays the credential.
- A MAC address is twelve hexadecimal digits, with
:or-between the pairs or none.00:11:62:00:00:0aand00116200000aare the same device. It cannot be all zeros, allfor a group address. - Set it when you add the printer, or later with
PATCH /v1/printers/{printer}andprinters:write.{"allowed_mac": null}removes it. - With a device named, the MAC the device reports must be that one. A request that reports none is refused too. The refusal is a bare
403, the same as for a wrong URL. - It needs a firmware that reports its MAC address. Only firmware 5.2 of a Star mC-Print3 has been seen to do it. If the
macof the printer readsnullafter it has connected, the printer does not report one, and it would be refused as soon as a device is named. An Epson reports no MAC at all, so a device cannot be named for it.
To avoid locking a printer out, connect it first without an allowed device. Read the mac that GET /v1/printers/{printer} shows, compare it with the label and the self-test print, and only then set it. Some models print the Wi-Fi MAC on the label and report the Ethernet one: name the one the printer reports. A mistyped MAC stops the printer behind a bare 403. The printer then shows the status mac_mismatch and reported_mac, which can take up to an hour to appear.
A change takes effect for a device that the new value leaves out within about a second. A device that it names, or any device after null, is let in about 30 seconds later, plus the printer’s poll interval.
Moving and replacing printers
- Move inside a customer:
POST /v1/printers/{printer}/movewith the newlocation. The URL does not change, and nothing changes on the printer. Jobs never move with a printer, so a printer with waiting jobs is refused with409 pending_jobs, unless you sendcancel_pending_jobs: true. A receipt for one hotel never prints in another. - Move to another customer: the host changes, so the printer gets a new URL, which the answer shows once. Enter it on the printer again. The old URL stops working at once. A Star prints the welcome receipt again.
- Move to another organization: this is not a move. A location must belong to your organization. Delete the printer and add a new one.
- Replace the hardware: with no allowed device, a new printer that holds the same URL just works, and brand and model follow the new device within a day. With an allowed device, change
allowed_macto the MAC of the new printer, or remove it. Nothing has to be released. A replaced printer behind the same URL prints no new welcome receipt.
Moving a printer and changing or deleting a customer or a location are done with the API and a key. The dashboard can add a printer, edit its name, profile and allowed device, rotate its secret, delete it and print a test page.
Own domain for printer URLs
Printer URLs can be on your own domain, for example print.example.com, as an extra on request. Tillcast sets the domain up for your organization, and the price is agreed individually: ask through the contact page. No API call sets a domain up. Once one is active for your organization, a printer made with domain left out gets its URL on it, and the domain of the printer says which one it has. The host of the URL is still <code>.<domain>, with the code Tillcast gives the customer.