nextX
← Docs

Security when integrating with NextX

What NextX guarantees, and what your systems must do to keep workspace data safe.

1. Credentials

  • An app's client_secret (nxs_…) and API keys (nxk_…) are shown once — if lost, create a new one; nobody can reveal it again.
  • OAuth2 tokens live 3600 seconds; the refresh_token field is always empty — request a new token when it expires.
  • One token per workspace (the workspace_id of the workspace that installed the app).
  • Keep secrets/keys on your server — never in mobile apps, browser code, repositories or logs.

2. Least-privilege scopes

  • Granted scope = requested ∩ allowed (app) ∩ granted (workspace consent) ∩ modules the workspace has bought — calls outside it get 403 (insufficient_scope on gateway-guarded routes, Permission required: … elsewhere).
  • The gateway enforces permissions per endpoint; the workspace chooses which scopes to grant on install.
  • Request only what you need — easier consent, smaller blast radius if a token leaks.

3. Signed webhooks

  • X-NextX-Signature-256: sha256=<hex> = HMAC-SHA256(secret, {ts}.{raw_body}) — computed over the raw body before JSON parsing.
  • Reject if X-NextX-Timestamp is off by more than ~5 minutes (replay protection).
  • De-duplicate by id (evt_…) — the same event can arrive more than once on retry.
  • The webhook secret (whsec_…, Standard Webhooks format; older webhooks may still have whk_sec_…) is returned only once — when a service's webhook is first created (created: true) or when you rotate it — store it safely.
  • whsec_… secrets also come with the standard webhook-id · webhook-timestamp · webhook-signature headers — verify them with the off-the-shelf standardwebhooks library instead of hand-written code.

4. Transport

  • HTTPS only. Webhook URLs pointing to internal/private IPs are blocked (SSRF guard) — public HTTPS only.
  • Endpoints must return 2xx within 15 seconds; failures/timeouts up to 8 delivery attempts (7 retries over ~24 hours), repeated failures trip a circuit breaker.
  • Default limit 600 requests/minute per app — on 429, read Retry-After and slow down.

5. Safe retries (Idempotency-Key)

  • Every write (POST/PUT/PATCH) made with an API key or app token accepts an Idempotency-Key header — generate one value (e.g. a UUID) for each operation.
  • If the network drops, resend with the same value within 24 hours ⇒ you get the original result back (header Idempotency-Replayed: true) and no second record is created. If the first call is still running ⇒ 409; wait a moment and retry.
  • Same value with a different path or body ⇒ 422 — never reuse a value for another operation. If the first call failed (non-2xx) the value is released, so a retry runs again.

6. Rotation and revocation

  • API keys: revoke in Settings → API Keys & Webhooks — takes effect almost immediately.
  • Zero-downtime key change: create a new key, let the partner switch, then revoke the old one.
  • Rotating a webhook secret keeps the old one valid for 7 days: during that time NextX sends X-NextX-Signature-256 (new secret) plus X-NextX-Signature-256-Previous (old secret) — accept either, then retire the old secret.

7. Reporting vulnerabilities

  • Send a description + reproduction steps to support@nextx.vn with a subject starting with [Security]. Please do not disclose publicly until NextX confirms a fix.
  • Test only on the sandbox https://api-dev.nextx.vn — never on real customer data.

Go-live checklist

☐ Secrets/keys live in a secret store — not in source code, never logged
☐ Request only the scopes you need
☐ Verify signature + timestamp on every webhook, de-duplicate by id, return 2xx within 15 seconds
☐ During secret rotation: accept the new OR Previous signature
☐ Send a fresh Idempotency-Key with every write; on a network retry reuse that same value
☐ Handle 401 (expired/revoked token or key) · 403 (missing scope) · 429 (wait Retry-After)
☐ Ran the full flow on the sandbox https://api-dev.nextx.vn

Regular integration questions also go to support@nextx.vn.