Authentication

Overview

The Labelary Compatibility API (Closed Beta) requires authentication on all requests. Every API call must include a valid API key using the X-API-Key header.

Obtaining an API Key

To get an API key:

Go to your API Keys page
Click Create API Key
Copy your API key and store it securely
Use it in your requests as shown below

Using Your API Key

Include your API key in the X-API-Key header on every request:

curl -X POST "https://api.zpl.tools/compatibility/labelary/v1/printers/8dpmm/labels/4x6/0" \
  -H "X-API-Key: your_api_key_here" \
  --data "^XA^FO50,50^FDHello World^FS^XZ"

For more examples, see the Quickstart guide.

Rate Limits

By default there are no per-key rate limits — new keys are unlimited.

You can optionally set soft limits per key from the API Keys page:

Requests per second — enforced immediately; requests over the limit receive a 429 with a Retry-After header.
Pages per day — rendered label pages per UTC day, enforced within a few minutes (usage is aggregated by the analytics pipeline); resets at midnight UTC.

A platform-level abuse limit also applies per organization. When any limit is hit the API returns a structured 429 — see the Error Reference for the response shape.

Troubleshooting

401 Error

If you receive a 401 (Unauthorized) error, check the following:

Ensure the X-API-Key header is included in your request
Check that the key is spelled correctly
Ensure you're using the full key (not a truncated version)
Verify the key hasn't expired or been revoked — an expired key returns {"error": "key_expired"}, an unknown or revoked key returns {"error": "invalid_key"}
Confirm the header name is exactly X-API-Key (case-sensitive)
Check that the header is not being stripped by proxies or middleware

A 403 (Forbidden) with {"error": "scope_denied"} means the key is valid but its scope does not allow the output format your request asked for (via the Accept header). Use a key scoped to that format (or all formats), or create one on the API Keys page.

Next Steps

Check the Error Reference for authentication error codes
Browse the API Reference for all available endpoints