Skip to main content
API keys allow external services and scripts to authenticate with the Naturalead API without a user session. Each key is scoped to an account and restricted to a specific set of RBAC permissions.

​
Key concepts

Scoped permissions

Each key is granted a subset of RBAC permissions. A key creator can only grant permissions they themselves hold.

Environment isolation

Keys are either live or test. Live keys use the prefix nl_live_ and test keys use nl_test_.

Shown once

The full key is returned only at creation (or rotation). It is hashed with SHA-256 before storage and can never be retrieved again.

Audit trail

All key lifecycle events (create, revoke, rotate, delete) are logged to the audit log for SOC2 compliance.

​
Step-by-step

​
Best practices

Follow these recommendations to keep your API keys secure and manageable.
  • Principle of least privilege — Grant only the permissions each integration actually needs. A CRM sync that only reads leads should not have leads:import or campaigns:manage.
  • Set expiration dates — Use expiresAt to enforce key rotation on a schedule. Keys without expiration remain active indefinitely.
  • Rotate regularly — Rotate keys at least every 90 days. Use the rotate endpoint for zero-downtime replacement.
  • Use environment separation — Use test keys during development and live keys in production. Never share keys across environments.
  • Never commit keys to source control — Store keys in environment variables or a secrets manager. If a key is accidentally exposed, revoke and rotate it immediately.
  • Monitor usage — Check the lastUsedAt field when listing keys. Keys that have not been used in a long time may be candidates for revocation.
  • Rate limits apply — API keys are subject to rate limiting (500 requests/minute per key, 1000 requests/minute per IP globally).

​
Required permissions