Authentication

What a key is for

Every call carries one key, and the key belongs to the workspace rather than to a person, so it keeps working when someone leaves. You create one under Account, API keys: the secret is shown once and what it may do is fixed by its scopes.

Every request carries an API key. You create one on the API keys screen in your account; it is shown once at creation and never stored in readable form.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

Never embed the key in a browser or mobile app. Make the calls from your own server.

Each key carries a set of scopes, so a key that only renders documents cannot modify templates.

templates:read   templates:write   documents:render
previews:manage  assets:read       assets:write
usage:read       api-keys:manage

A call that works, and one that does not

The first call lists your templates. The second sends a key that was revoked, and the answer says exactly that.

# The key lives in the environment, not in the code
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized request",
  "status": 401,
  "detail": "The API key is invalid.",
  "correlationId": "0123b82d0a59e8b196a783af0e0e86bc"
}

Every error body carries a correlationId. Quote it when you write to support and the request can be found in the logs without guessing.

What usually goes wrong

• The key goes in the X-PDFgine-Key header. An Authorization: Bearer token is not read at all, so the call answers 401 even though the key is valid.
• 401 and 403 mean different things. 401 is "I do not know who you are"; 403 is "I know you, but this key has no such scope" - a key without templates:write cannot save a template. Scopes are fixed when the key is created.
• The secret is shown once. If it is lost there is no way to read it again; revoke that key and create another.
• A key never belongs in a browser or a mobile app. Anything shipped to a device can be read off it; call PDFgine from your own server.
• Revoking takes effect on the very next call. Deploy the new key first, then revoke the old one, or the calls in flight fail.