Skip to main content
All API requests authenticate via Bearer tokens in the Authorization header. Keys are scoped to your organization and inherit the permissions of the user who created them.

​
Base URL

https://nearnode.io/api/v1

​
Authentication Header

curl https://nearnode.io/api/v1/nodes \
  -H "Authorization: Bearer sk_live_..."
Every request without a valid Authorization header returns 401 Unauthorized.

​
API Key Types

PrefixEnvironmentUse Case
sk_live_ProductionLive scan traffic, production integrations
sk_test_SandboxDevelopment and testing — no real scan data affected
Ops Tip: Generate and manage API keys in the Dashboard under Developers → API Keys. No API call required.

​
Generating a Key

1

Navigate to API Keys

Open Developers → API Keys in the NearNode Console.
2

Create Key

Click Create Key. Assign a label (e.g., n8n-production, mobile-app-v2).
3

Copy Immediately

The full key is shown once. Copy it to your secrets manager. It cannot be retrieved again.
4

Set Permissions (Optional)

Restrict the key to specific scopes: nodes:read, nodes:write, batches:write, analytics:read, webhooks:manage.
API keys grant access to your entire organization’s data by default. Use scoped keys in production to enforce least-privilege access.

​
Key Scopes

ScopeDescription
nodes:readList and retrieve nodes
nodes:writeCreate, update, and delete nodes
batches:readList and retrieve batches
batches:writeCreate batches and trigger generation
analytics:readQuery scan analytics
webhooks:manageCreate, update, and delete webhooks
templates:manageCreate, update, and delete templates
A key with no explicit scopes has full access (equivalent to the creating user’s role).

​
Response Format

All responses follow a consistent envelope: 
// Success
{
  "data": { ... },
  "error": null
}

// Error
{
  "data": null,
  "error": "Description of what went wrong"
}

​
HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad request — invalid input
401Unauthorized — missing or invalid API key
403Forbidden — key lacks required scope
404Resource not found
422Validation error
429Rate limited — see Rate Limits
500Internal server error

​
Key Rotation

Rotate keys without downtime:
  1. Create a new key with the same scopes
  2. Update your integration to use the new key
  3. Verify traffic flows on the new key (check Developers → API Keys → Last Used)
  4. Revoke the old key
Label your keys with the integration name and creation date (e.g., crm-sync-2026-02). This makes rotation auditable.

​
Security Best Practices

API keys belong in server-side code, environment variables, or secrets managers. Never embed them in frontend JavaScript, mobile apps, or version control.
A key that only needs to read analytics should not have nodes:write access. Scope keys to the minimum permissions required.
Rotate production keys every 90 days. The Dashboard shows Last Used timestamps to identify stale keys.
The Developers → API Keys page shows request counts and last-used timestamps per key. Unusual spikes may indicate a compromised key.