Skip to content

API keys and errors

The public API lives under /api/v1 and takes only API keys, sent in the x-api-key header. Session cookies don’t work there, and keys don’t work on the app’s own /api routes.

Terminal window
curl -H "x-api-key: $NECODOC_API_KEY" https://necodoc.example.com/api/v1/templates

Every response carries X-Request-Id. Send your own (letters, digits, ., :, _, -, up to 128 characters) to trace a call across systems; it’s recorded on the generation.

  • Personal keys belong to you and act as you. Create them under Developers › API keys. Any user with a role can.
  • Service accounts are identities for systems: a billing integration, a nightly job. They have a name, a description, an owner contact and roles, and can’t sign in. Admins create them under Admin › Service accounts and manage their keys there. Keys on a service account keep working when the person who made them leaves.

Disabling a service account, or banning a user, stops all their keys at once. Admins see every key under Admin › API keys, with usage and a link to the generations each one made.

A key has:

  • a name, shown in lists and in the generation log
  • scopes (below)
  • an optional expiry, in days
  • an optional list of templates it may use; empty means every template its owner can see
  • an optional IP allowlist of addresses and CIDR ranges (203.0.113.7, 198.51.100.0/24, 2001:db8::/32); empty means any address
  • a rate limit in requests per hour (default 7200)

The secret starts with nd_ and is shown once. Store it in your secret manager; a lost key is replaced, not recovered. Lists show its first characters, when it was created and last used (and from where), its total requests, and a warning when it expires within 14 days.

Scopes and the other settings are fixed when the key is made. To change them, rotate or make a new key.

Scope Allows
render:html POST /render
templates:read GET /templates, GET /templates/:id, GET /templates/:id/versions/:version/schema
templates:generate POST /templates/:id/versions/:version/generate
batches:write POST /templates/:id/versions/:version/batch
batches:read GET /batches/:id, .../zip, .../packet
generations:read GET /generations/:id, .../pdf, .../signing-package, POST .../link
combine:write POST /combine

Every scope needs its owner to hold a role with document: view (all roles do). A key is checked against its owner’s roles on every call, so removing someone’s roles stops their keys too.

A key reads only its owner’s own generations and batches.

Rotate makes a replacement with the same settings and shows its secret once. The old key keeps working for an overlap window (24 hours by default, up to 30 days), then expires. Deploy the new secret within the window. Rotating with an overlap of 0 stops the old key at once.

Revoke stops a key immediately. Revoked and expired keys stay listed, so the generation log still names them.

Each key allows its number of requests per hour, counted over the last 60 minutes and shared by every API replica. Past that, calls answer 429 with Retry-After: the seconds until enough of the counted requests age out. Calls refused while blocked don’t count, so retrying doesn’t extend the block, but it doesn’t help either. Wait out Retry-After.

Errors are JSON:

{ "error": "This key needs the templates:read scope", "code": "missing_scope" }

Invalid input adds fieldErrors (field path → messages). A failed render adds the generationId of the logged failure.

Status code Meaning
401 missing_key No x-api-key header.
401 invalid_key Unknown key.
401 key_revoked The key was revoked.
401 key_expired The key expired (or its rotation overlap ended).
401 owner_disabled The key’s user is banned or its service account is disabled.
403 ip_not_allowed The caller’s address isn’t on the key’s allowlist.
403 missing_scope The key lacks the scope this call needs.
403 owner_forbidden The owner no longer has a role that allows it.
403 template_not_allowed The key is limited to other templates.
400 malformed_body The body isn’t valid JSON or form data.
404 not_found No such template, version, batch or generation, or it isn’t the owner’s.
409 template_archived The template is archived.
413 body_too_large The body is over 20 MB.
422 invalid_request The body or path doesn’t match the schema.
422 invalid_data Template data fails the version’s fields; see fieldErrors.
422 invalid_input A combine input isn’t a PDF or a generation with one.
422 render_failed The render failed (Liquid error, timeout); see generationId.
429 rate_limited Over the key’s rate limit; see Retry-After.
500 internal_error Unexpected server error.

IP allowlists compare the address the API sees. Behind a reverse proxy or load balancer, set TRUST_PROXY to the number of proxies in front of the API so it reads the client from X-Forwarded-For (see Configuration). Without it every call appears to come from the proxy.

Each deployment serves its OpenAPI 3.1 document at /api/v1/openapi.json, no key needed. The API reference here, the app’s Developers › API reference page and the SDKs are generated from it.