Authentication and API keys

Every request to the API, except health, carries an API key in its Authorization header. A key belongs to your organisation and acts for it within its scopes. Whoever runs Paprika for you issues your first key; with it you can make more.

The examples on these pages use the address and key the tutorial sets:

export PAPRIKA_URL=https://paprika.example.com
export PAPRIKA_KEY=ppk_…

Send the key

Send it as a bearer token:

curl -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/templates"

Without one, or with one that’s wrong, revoked or expired, the answer is 401:

curl "$PAPRIKA_URL/v1/templates"

{
  "code": "unauthorized",
  "message": "A valid API key is required: Authorization: Bearer ppk_…",
  "requestId": "7c1e9a02"
}

Scopes

Scope	Allows
render	Reading templates and versions, rendering, jobs, batches, outputs and named resources, reading the font library
publish	Making templates and versions, changing the font library and brand kits
keys	Your organisation’s own keys and webhooks

A request outside its key’s scopes is 403 scope-missing. Give each system the scopes it needs and no more: a website that renders documents needs only render.

Manage your keys

With a keys key you can list your organisation’s keys, make new ones (never with scopes the key you use hasn’t got), rotate them and revoke them. See the keys operations.

curl -H "Authorization: Bearer $PAPRIKA_KEY" -H "Content-Type: application/json" -d '{"name": "website", "scopes": ["render"]}' "$PAPRIKA_URL/v1/keys"

The answer is the only time the new key’s secret is shown, in key; keep it somewhere safe:

{
  "key": "ppk_Vb7Qm2Rk9TxW_s3cr3tExampleOnly",
  "id": "Vb7Qm2Rk9TxW",
  "name": "website",
  "scopes": ["render"],
  "expiresAt": null,
  "revokedAt": null
}

To replace a key without stopping the system using it, rotate it: you get a new key, and the old one keeps working for 24 hours while you change over.

curl -X POST -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/keys/Vb7Qm2Rk9TxW/rotate"

A key that may have leaked is revoked at once:

curl -X DELETE -H "Authorization: Bearer $PAPRIKA_KEY" "$PAPRIKA_URL/v1/keys/Vb7Qm2Rk9TxW"