> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nearnode.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API key management, bearer token auth, and key scoping.

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

```bash theme={null}
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 |

<Info>
  **Ops Tip:** Generate and manage API keys in the Dashboard under **Developers → API Keys**. No API call required.
</Info>

## Generating a Key

<Steps>
  <Step title="Navigate to API Keys">
    Open **Developers → API Keys** in the NearNode Console.
  </Step>

  <Step title="Create Key">
    Click **Create Key**. Assign a label (e.g., `n8n-production`, `mobile-app-v2`).
  </Step>

  <Step title="Copy Immediately">
    The full key is shown **once**. Copy it to your secrets manager. It cannot be retrieved again.
  </Step>

  <Step title="Set Permissions (Optional)">
    Restrict the key to specific scopes: `nodes:read`, `nodes:write`, `batches:write`, `analytics:read`, `webhooks:manage`.
  </Step>
</Steps>

<Warning>
  API keys grant access to your entire organization's data by default. Use scoped keys in production to enforce least-privilege access.
</Warning>

## 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:

```json theme={null}
// 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](/developers/rate-limits) |
| `500` | Internal 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

<Tip>
  Label your keys with the integration name and creation date (e.g., `crm-sync-2026-02`). This makes rotation auditable.
</Tip>

## Security Best Practices

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Use scoped keys">
    A key that only needs to read analytics should not have `nodes:write` access. Scope keys to the minimum permissions required.
  </Accordion>

  <Accordion title="Rotate regularly">
    Rotate production keys every 90 days. The Dashboard shows **Last Used** timestamps to identify stale keys.
  </Accordion>

  <Accordion title="Monitor usage">
    The **Developers → API Keys** page shows request counts and last-used timestamps per key. Unusual spikes may indicate a compromised key.
  </Accordion>
</AccordionGroup>