Authentication · Raven Docs

Getting a key

In the dashboard: Access → API Keys → New key. Give it the name of the system that will use it, not of a person. You will be reading this list in two years trying to work out what breaks if you delete a row.

The key is shown once. There is no endpoint that returns it again; if it is lost, delete it and issue another.

Using a key

Send it on every request, in either header:

GET /printers HTTP/1.1
Host: raven-api.formfl.be
Authorization: ApiKey rvn_live_9f2c…

X-Api-Key: rvn_live_9f2c… is accepted as an equivalent, which is convenient when something in your stack reserves Authorization for itself.

What a key reaches

Everything in your integrator: every connector, every device, every venue. See Your account is your business for why that matters more than it sounds.

The documented integrator surface is:

Printers: print, render a preview, test print
Scales: weigh, tare, read history
Bridges: the transparent proxy
Interactions: read one, cancel one
Integrator statistics

The API reference is generated from the running service, so it is the authority on request and response shapes. It describes the whole of your contract: anything it does not list is not part of the integrator surface.

Auth errors

Code	Means	Do
`401`	No key, malformed header, or a key that has been deleted.	Check the header name and that the key still exists in the dashboard.
`403`	Authenticated, but the route is not part of the integrator surface.	Use a documented endpoint; do not retry.
`404`	The id does not exist or is not yours.	Treat as "not mine". The API does not distinguish the two: confirming that an id exists would disclose something about an integrator that is not yours.

Rate limits

Over the limit, every endpoint answers 429 with nothing done. Two windows apply:

Calls	Limit	Scope
Print, weigh, tare, bridge	200 per minute	Back off with jitter rather than on a fixed timer, and do not treat it as a hard quota you can pace against exactly.
Preview render	120 per minute, per key	Counted separately, so previewing cannot exhaust your print allowance.

A 429 on a print submission means the job was never accepted, so retrying it with the same idempotency key is safe and is what you should do.

Rotation

Create the new key, deploy it, verify traffic on it, then delete the old one. Deletion takes effect immediately. There is no overlap window granted for you, so the overlap has to be two live keys that you retire in that order.

Issue a separate key per system that calls Raven (your ordering backend, your monitoring job) so one can be revoked without an outage everywhere.