Authentication

Applications call the Prynt API with a workspace API key. People use the web app with their own account and session; keys are for servers: your ERP, WMS, e-commerce backend or batch jobs.

Workspace API keys#

A key belongs to one workspace and can only render that workspace's templates with its data sources. Each key has a name, a mode (live or test), a set of scopes, a default environment and an optional expiration date.

• The full key looks like prynt_live_k3x9a2mq_…: a visible prefix (prynt_live_k3x9a2mq) that identifies the key in lists and logs, followed by the secret.
• The secret is shown once, when the key is created. Prynt stores only a hash and can never show it again.
• Every render records the key that asked for it: the Logs page shows the key's name and prefix next to each run.

Live and test keys#

Keys start with prynt_live_ or prynt_test_. Live keys are for production systems and may use every environment. Test keys are for development, staging and automated tests: a request of a test key for a production environment fails with 403 ENVIRONMENT_NOT_ALLOWED, so a test system can never read production data by mistake. The prefixes also make a leaked key easy to recognize for you and for secret scanners.

The key's default environment is used when a request does not name one (environment in the render request). Live keys default to production, test keys to development.

Scopes#

Scopes limit what a key can do. Grant only what the application needs: most integrations need only render.

Sending the key#

Send the key in the Authorization header as a bearer token, over HTTPS. The API lives under /api/v1 of https://api.prynt.it.

curl https://api.prynt.it/api/v1/templates \  -H "Authorization: Bearer prynt_live_..." \  -H "Prynt-Workspace: 0199b8a1-…"

The Prynt-Workspace header

The key already identifies its workspace, so the Prynt-Workspace header is optional. When you send it (the workspace id shown in the API explorer), Prynt checks that the key belongs to that workspace and answers 403 WORKSPACE_MISMATCH otherwise: a cheap guard against a key of the wrong workspace in a configuration file.

Creating and revoking keys#

• In the web app, open Developers → API keys (permission apikeys.manage: owners, admins and developers) and choose Create API key. Pick the mode, the scopes, the default environment and an expiration (never, 30, 90 or 365 days, or a date).
• Copy the key from the dialog: it will not be shown again.
• Revoke a key from the same page. Revocation is immediate: the next request with that key fails with 401 API_KEY_REVOKED.
• To rotate a key without downtime, create a new key, deploy it to your application, check in the Logs page that requests use it, then revoke the old one.

Rate limits#

Each key may send up to 600 requests per minute by default. Beyond that the API answers 429 Too Many Requests with errorCode RATE_LIMITED and a Retry-After header with the seconds to wait. Retry after that delay, with exponential backoff and some jitter; for large batches prefer asynchronous renders (async: true).

HTTP/1.1 429 Too Many RequestsRetry-After: 12Content-Type: application/problem+json {  "title": "Too many requests",  "status": 429,  "errorCode": "RATE_LIMITED",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}

Authentication errors#

Like every error of the API, authentication failures are RFC 9457 problem details with a stable errorCode and the correlationId of the request.