Authentication

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

Prefix	Environment	Use Case
`sk_live_`	Production	Live scan traffic, production integrations
`sk_test_`	Sandbox	Development 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

Navigate to API Keys

Open Developers → API Keys in the NearNode Console.

Create Key

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

Copy Immediately

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

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

Scope	Description
`nodes:read`	List and retrieve nodes
`nodes:write`	Create, update, and delete nodes
`batches:read`	List and retrieve batches
`batches:write`	Create batches and trigger generation
`analytics:read`	Query scan analytics
`webhooks:manage`	Create, update, and delete webhooks
`templates:manage`	Create, 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

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

Key Rotation

Rotate keys without downtime:

Create a new key with the same scopes
Update your integration to use the new key
Verify traffic flows on the new key (check Developers → API Keys → Last Used)
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

Never expose keys client-side

API keys belong in server-side code, environment variables, or secrets managers. Never embed them in frontend JavaScript, mobile apps, or version control.

Use scoped keys

A key that only needs to read analytics should not have nodes:write access. Scope keys to the minimum permissions required.

Rotate regularly

Rotate production keys every 90 days. The Dashboard shows Last Used timestamps to identify stale keys.

Monitor usage

The Developers → API Keys page shows request counts and last-used timestamps per key. Unusual spikes may indicate a compromised key.

Getting Started

Core Features

Developer Console

Enterprise Governance

Base URL

Authentication Header

API Key Types

Generating a Key

Key Scopes

Response Format

HTTP Status Codes

Key Rotation

Security Best Practices

​Base URL

​Authentication Header

​API Key Types

​Generating a Key

​Key Scopes

​Response Format

​HTTP Status Codes

​Key Rotation

​Security Best Practices

Base URL

Authentication Header

API Key Types

Generating a Key

Key Scopes

Response Format

HTTP Status Codes

Key Rotation

Security Best Practices