# Needle: authentication for agents

> How an AI agent or script gets access to a Needle account. Generated from the API's scope registry. Full docs: https://useneedle.net/docs/mcp and https://useneedle.net/docs/api.

Every Needle API and MCP call acts for one Needle account. There is no anonymous access: the account owner either signs in (OAuth) or creates an API key. API and MCP access are included in the **Growth** and **Scale** plans.

## Pick a method

| You are | Use | Endpoint |
| --- | --- | --- |
| An MCP client that supports OAuth (claude.ai, ChatGPT, Claude Code, Cursor) | OAuth sign-in | `https://api.useneedle.net/mcp` |
| An MCP client that can only send headers | API key | `https://api.useneedle.net/mcp` |
| A script, n8n, Make, Zapier or Clay | API key | `https://api.useneedle.net/v1` |

OAuth access tokens work on the MCP server only. The REST API takes API keys.

## OAuth (MCP)

Needle is an OAuth 2.1 authorization server: authorization code with PKCE (S256), public clients (no client secret), rotating refresh tokens.

1. Call `https://api.useneedle.net/mcp` without a token. The `401` carries `WWW-Authenticate: Bearer resource_metadata="https://api.useneedle.net/.well-known/oauth-protected-resource/mcp"`.
2. Read the protected resource metadata, then the authorization server metadata at `https://api.useneedle.net/.well-known/oauth-authorization-server`.
3. Identify your client with a Client ID Metadata Document (preferred) or register at the `registration_endpoint` (dynamic client registration).
4. Send the user to the `authorization_endpoint`. They sign in to Needle and choose **Allow**. Request `offline_access` to get a refresh token.
5. Exchange the code at the `token_endpoint` and send `Authorization: Bearer <access token>` on every MCP request.

Supported scopes: `leads:read`, `leads:write`, `search:run`, `drafts:write`, `trending:read`, `offline_access`.

The user sees and disconnects connected apps in **Settings → API & MCP**. Disconnecting stops access right away.

## API keys

The account owner creates a key in **Settings → API & MCP** (https://useneedle.net/settings). Keys start with `ndl_live_`, are shown once, and can be revoked at any time.

Send the key as `Authorization: Bearer ndl_live_…` (or `x-api-key: ndl_live_…`). Never put it in a URL. An agent should ask its user for a key; it cannot create one itself.

## Scopes

| Scope | Allows |
| --- | --- |
| `leads:read` | Read your brands and leads |
| `leads:write` | Change lead status (replied, done, dismissed) |
| `search:run` | Run searches (uses your daily search runs) |
| `drafts:write` | Generate reply drafts (uses your daily drafts) |
| `trending:read` | Read trending problems |

A call without the right scope fails with `insufficient_scope`, and `details.required_scope` names the missing one.

## Rules for agents

- Needle never posts to any community. Reply drafts are text for the user to review and post themselves.
- Searches and reply drafts use the account's daily limits, shared with the dashboard. Call `get_usage` (free) when a limit error appears.
- On `401 invalid_token` with OAuth, refresh and retry once. With an API key, ask the user for a new key.

## Discovery

- MCP server card: https://useneedle.net/.well-known/mcp/server-card.json
- MCP discovery: https://useneedle.net/.well-known/mcp.json
- API catalog (RFC 9727): https://useneedle.net/.well-known/api-catalog
- OpenAPI 3.1: https://api.useneedle.net/v1/openapi.json
- llms.txt: https://useneedle.net/llms.txt
- Support: support@useneedle.net