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

# Authentication

> Authenticate every API request using your NearIQ API key.

## API key authentication

Include your API key in every request using the `X-NearIQ-Key` header:

```bash theme={null}
curl https://app.neariq.io/api/v1/me \
  -H "X-NearIQ-Key: niq_your_key_here"
```

## Key format

API keys follow this format:

```
niq_live_<48-character-hex-string>
```

Example: `niq_live_your_api_key_here`

Keys are case-sensitive and must be kept secret. Do not expose them in client-side code, public repositories, or URLs.

## Generating and revoking keys

Keys are managed in **Settings** → **API**:

* **Generate** — creates a new key. The full key is only shown once at creation.
* **Revoke** — immediately invalidates the key. All requests using it will return `401`.

## Key scopes

API keys can be limited to the parts of the API an integration needs. Existing keys keep their stored scopes. Keys created without an explicit scope list use the default read-only scope set. API-key management itself is dashboard-session only.

| Scope                 | Allows                                                                                                                                                          |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `competitors:read`    | Business profile, competitors, reviews, snapshots, GBP health, gap analysis, AI visibility, content history, Engagement Report Card, and GBP insights endpoints |
| `alerts:read`         | Alert list endpoints                                                                                                                                            |
| `export`              | Account export endpoint                                                                                                                                         |
| `webhooks:manage`     | Create, list, update, and delete webhook endpoints                                                                                                              |
| `usage:read`          | Usage and API key metadata endpoints                                                                                                                            |
| `content:write`       | Generate and refine Content Studio drafts                                                                                                                       |
| `payments:write`      | Record CRM payment rows                                                                                                                                         |
| `chat:write`          | Send non-streaming v1 API chat messages                                                                                                                         |
| `competitors:write`   | Add tracked competitors through the v1 API and Zapier actions                                                                                                   |
| `business:write`      | Update business profile fields                                                                                                                                  |
| `alerts:write`        | Mark alerts read or unread                                                                                                                                      |
| `contacts:write`      | Create CRM contacts                                                                                                                                             |
| `embeds:write`        | Create read-only chart embed tokens                                                                                                                             |
| `notifications:write` | Update notification delivery settings, including webhook/SMS destinations                                                                                       |
| `reports:write`       | Create stored intelligence report records                                                                                                                       |
| `reviews:write`       | Create review request records                                                                                                                                   |
| `social:write`        | Create and schedule social posts                                                                                                                                |

## Error responses

| Status             | Meaning                                                            |
| ------------------ | ------------------------------------------------------------------ |
| `401 Unauthorized` | Key is missing, invalid, or revoked                                |
| `403 Forbidden`    | Key is valid but your plan or key scopes do not allow the endpoint |

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
```

## Security best practices

* Store keys in environment variables, never hardcoded
* Use one key per integration so you can revoke selectively
* Rotate keys periodically
* Never log or print API keys