Guide

API keys

An API key lets another program — your accounting system, a script, a Zapier step — generate documents from your templates without a person signing in. This guide covers making, protecting and removing keys. The technical side (what to send, what comes back) is in the API documentation; this page is about the key itself.

You do not need a key to use Ristmark by hand. Keys are only for software that calls the API.

Who can make keys

Only the workspace Owner. The API keys section of Settings is not shown to Admins, Managers or Members. See Teams and people.

Create a key

Open Settings → API keys.
Type a Label that says what the key is for ("Accounting export", "CI pipeline"). You will use it to tell keys apart later.
Choose an expiry: Never expires, Expires in 30 days, 90 days or in a year. A key that never expires is the riskier default; if the integration is a one-off or you plan to rotate it, choose a window.
Choose the Team. A generation key only sees that team's approved templates; an authoring key works with that team's draft templates. The default is your Default team. The key's team cannot be changed later; to use a key with another team, create a new key.
Choose What is this key for?: Generate documents from my system (a generation key, the default) or Build and edit draft templates (Beta) (an authoring key). The kind is fixed when the key is made.
Choose what this key may do (see Permissions below). For a generation key, Generate documents and List templates are on and Export templates is off. For an authoring key, Read drafts, Create and edit drafts and Preview drafts are on; Upload pictures and Copy approved templates are off.
Press Create key.

Permissions

Each key has an explicit set of permissions. A key can do only what you switch on:

Generate documents — create documents from approved templates. Costs one credit for every two rendered pages, rounded up per document.
List templates — see which approved templates the key's team has.
Export templates — download an approved template's design and pictures. Off by default; turn it on only for an integration that needs it.

A key needs at least one permission. For a generation key the permissions are independent: for example, a key that can only list templates is allowed. A call the key has no permission for is refused.

Authoring keys (Beta)

An authoring key lets software, usually an AI coding agent, build and edit draft templates. It cannot generate documents, and a generation key cannot do any of this. Its permissions are:

Read drafts — see the team's drafts. Every authoring key needs this one. (The list of approved templates it could copy also needs Copy approved templates.)
Create and edit drafts — create drafts, change them and check them. Needs Read drafts.
Preview drafts — render a draft with sample data into a watermarked PDF preview. Needs Read drafts. A preview uses no generation credits.
Upload pictures — add new PNG or JPEG pictures for drafts. Needs Create and edit drafts. Off by default.
Copy approved templates — start a new draft from a copy of an approved template, and read an approved template's contents. Needs Create and edit drafts. Off by default.

Settings shows why a switch is locked: Read drafts is always on for an authoring key; Create and edit drafts stays on while uploads or copying are on; and Upload pictures and Copy approved templates cannot be switched on until Create and edit drafts is on.

Drafts an authoring key makes go to your review queue. A person approves them; the key never changes an approved template. The full picture is in Authoring API (Beta).

To change a live key's permissions, press Edit on its row, switch permissions on or off and press Save permissions. The change applies at once. If another owner changed the same key's permissions after you opened the list, saving is refused with "Someone else changed this key's permissions — check and save again." The row is reloaded with the current permissions; check them and save again, so one person's change never silently overwrites another's.

Keys made before permissions existed were revoked when permissions were introduced. They stay in the list as "Revoked — made before key permissions" and cannot be edited. Create a new key instead.

The key list shows each key's Team, its kind (Generation, or Authoring · Beta) and its permissions as short badges (for example Generate, List, Export, or Read drafts, Edit drafts, Preview, Upload, Copy). Editing permissions works the same way for both kinds.

The key is shown once

A box appears: "Copy your new key now — it won't be shown again." The key looks like plk_live_ followed by a long run of letters and digits. Press Copy and paste it into the place where your software keeps its secrets (a password manager, your hosting provider's secret store, a CI secret). Then press Done.

Ristmark stores only a fingerprint of the key, not the key. That is why it cannot show it again. If you lose it, create a new key and revoke the old one. The Settings window will not close while the key is still on screen, so you do not lose it by accident.

The list afterwards shows only the prefix (the first characters followed by "…"), the label, when it was Created, when it was Last used, and when it Expires. An expired key is marked Expired and stops working.

Use the key

Send the key with each request, either way:

x-api-key: plk_live_xxx
Authorization: Bearer plk_live_xxx

The Using your key note on the page shows a ready-to-edit curl example. Every call is made to https://api.ristmark.app/v1/…. A generation key opens only what its permissions allow, out of these four things (an authoring key uses a separate set of calls, described in Authoring API (Beta)):

generate one document (POST /v1/documents) — needs Generate documents,
generate a batch of up to 25 (POST /v1/documents/batch) — needs Generate documents,
list your approved templates (GET /v1/templates) — needs List templates,
export an approved template, with the pictures it uses (GET /v1/templates/{id}/export) — needs Export templates.

With a generation key, only approved templates can be generated (see Approval and versions), and only those of the team the key belongs to, the team you chose when you made it. Generating costs one credit for every two rendered pages, rounded up per document, billed to your workspace, exactly like generating by hand; listing and exporting cost nothing. Generating is limited to 30 requests a minute per workspace.

What a leaked key can do

Assume a key that has been pasted into a chat, committed to a repository, printed in a log or sent by email is public. What someone can do with it depends on its kind. Give each key only the permissions its integration needs.

A generation key, for its team's approved templates only:

with Generate documents: spend your generation credits by generating documents, until credits or your plan's limit run out,
with List templates: see which approved templates the team has, and
with Export templates: read an approved template and its pictures (text, layout, fields and any image or letterhead it uses).

It cannot:

edit, create or delete templates, pictures or settings,
see or change your billing, plan or credits,
read or create people, teams or other keys,
reach templates that are still in review, or other teams' templates.

An authoring key, for its own team only, with the permissions it was given:

with Read drafts: read the team's authoring drafts (those made through authoring keys), including their content,
with Create and edit drafts: create drafts, replace the content of any such draft, and move to Trash the drafts that this key made. Nothing it makes is live until a person approves it, and it cannot change an approved template,
with Preview drafts: render previews, each of which is a rendering job on your workspace,
with Upload pictures: add PNG or JPEG pictures, and reference any picture in the team, including ones other people uploaded (picture access is not private within a team), and
with Copy approved templates: list the team's approved templates, read their contents, and copy them into new drafts.

It cannot generate documents, approve anything, change an approved template, trash drafts made by a person or another key, see billing, plan or credits, read or create people, teams or other keys, or reach other teams' templates.

A key is not a login to your workspace. It can still cost money and expose templates, so treat it like a password.

If a key leaks: revoke it

Open Settings → API keys.
Find the key by its label or prefix and press Revoke.
Confirm: "Revoke this key? Any client using it will immediately get 401."

The key stops working immediately, for everyone, and cannot be restored. Then create a new key and update your software. Check Usage in Settings and your credit balance for any unexpected use.

Rotating a key without downtime

Create a new key with the same label plus the date.
Put it into your software and deploy.
Watch the old key's Last used until it stops changing.
Revoke the old key.

Good habits

One key per integration, labelled by what it does, so revoking one does not break the others.
Never put a key in a web page, a mobile app or any code that runs on a customer's device — keep it on your server.
Give keys an expiry unless the integration is permanent.
Remove keys for integrations you no longer run.
Send only business documents' data. The same rules apply to what you send through the API as to what you type in the editor: no payment-card numbers, health or other sensitive personal data. Ristmark is for business use.

If something looks wrong

I get 401. The key was revoked, has expired, was copied with a missing character, or is sent in the wrong header. Create a new one.
I get 403. The key does not have the permission for that call. Press Edit on its row and switch it on, or use a key that has it.
I get 404 for a template that exists. The template is still in review, deleted, or belongs to a team the key does not reach.
I get 402. Your plan is not active or you are out of credits.
I get 429. You exceeded the request limit; slow down and retry.
I lost my key. Create another and revoke the lost one. There is no way to show it again.
I can't change a key's team. A key's team is fixed when it is made. Create a new key for the other team.
There is no API keys section in my Settings. You are not the Owner.

See the API documentation for request fields, strict mode, render warnings and the full list of status codes.