← Docs

Security when integrating with Nextfarm

What Nextfarm guarantees, and what your system must do to keep farm data safe.

1. Credentials

  • API keys (nfk_…) and client_secret values (nfs_…) are shown only once, at creation. Nextfarm stores only a SHA-256 hash — if you lose one, create a new one; nobody can recover it.
  • App (OAuth) tokens live for 15 minutes with no refresh token — request a new one when it expires.
  • Keep keys and secrets on your server (environment variables, secrets manager). Never embed them in mobile apps, browser-side websites, code repositories or logs.

2. Least privilege

  • Each key or app can only use the scopes it was granted; calls outside them return 403.
  • Whoever creates a key or installs an app can only grant scopes they hold themselves — no privilege escalation through keys.
  • There are no device-control scopes, and keys cannot reach user/permission administration. Writes are allowed on only a few routes (declaring harvest batches, adding/editing book rows).
  • Ask only for what you need — farms approve more readily, and a leaked key does less damage.

3. Signed webhooks

  • X-Nextfarm-Signature = sha256= + hex of HMAC-SHA256(secret, timestamp + "." + body). Compute it over the raw body and compare in constant time.
  • Reject messages whose X-Nextfarm-Timestamp is off by more than 5 minutes — this blocks replayed messages.
  • De-duplicate on X-Nextfarm-Delivery — Nextfarm may deliver a message again when retrying.
  • The whsec_… secret is shown once, on creation or rotation. Node.js / Python samples →
  • Every message also carries the Standard Webhooks headers (webhook-id · webhook-timestamp · webhook-signature) — verify them with the off-the-shelf standardwebhooks library instead of hand-written code. How →

4. Transport

  • HTTPS only. Webhook URLs must be https:// to a public server; private addresses (localhost, 10.x, 172.16–31.x, 192.168.x, 169.254.x…) are blocked both when saving and when sending.
  • Webhooks do not follow redirects (3xx counts as a failure) and wait at most 10 seconds.
  • Rate limits apply per farm: on 429, read Retry-After and call again — don't hammer the API.

5. Rotation and revocation

  • API keys: the farm owner revokes them in System › API keys — later calls return 401 immediately.
  • Webhooks: Rotate secret in System › Webhooks — the old secret keeps co-signing for 7 days (X-Nextfarm-Signature-Previous header + a second signature in webhook-signature) so receivers can switch over.
  • Apps: when a farm removes an app in System › Apps or changes its scopes, or NextFarm suspends it, existing tokens are blocked immediately. Partners rotate the App Secret in My apps › App settings › App Secret; the old secret keeps working for 24 hours.
  • Suspect a leaked key or secret? Revoke or rotate first, investigate later.

6. Reporting vulnerabilities

  • Send a description and reproduction steps to [email protected] with a subject starting with [Security]. Please don't disclose it publicly until Nextfarm confirms a fix.
  • Test on your own Developer workspace (free, with sample data, nothing sent outside) — never test writes against a customer's real farm.
  • Regular integration questions go to [email protected] as well.

Go-live checklist

Example
☐ Keys/secrets live in a secrets manager — not in source code, never printed to logs
☐ Request only the scopes you need
☐ Verify signature + timestamp on every webhook, de-duplicate on X-Nextfarm-Delivery, return 2xx within 10 seconds
☐ Writes: send a unique Idempotency-Key per record; on a lost response retry with the SAME key, never a new one
☐ Handle 401 (key revoked/expired) · 403 (missing scope) · 429 (wait for Retry-After)
☐ App tokens: request a new one every 15 minutes, don't store them long-term
☐ Ran the full flow end to end on your test farm