# LeadLists auth.md

How AI agents and API clients authenticate to LeadLists.

## Who this is for

Agents acting for a LeadLists user: MCP clients (Claude, ChatGPT, Cursor, Windsurf, Gemini CLI, n8n) and scripts
calling the REST API. Every credential belongs to a signed-in LeadLists user and spends that user's lead allowance.
There is no anonymous access and no endpoint where an agent can register itself without a person.

## Option 1: OAuth 2.1 (MCP clients)

- Protected resource: `https://leadlists.app/mcp`
- Protected resource metadata (RFC 9728): https://leadlists.app/.well-known/oauth-protected-resource/mcp
- Authorization server metadata (RFC 8414): https://leadlists.app/.well-known/oauth-authorization-server
- Dynamic client registration (RFC 7591): `POST https://app.leadlists.app/oauth/register`
- Authorization code flow with PKCE (S256 only), public clients (`token_endpoint_auth_method: none`)
- Scope: `leads`
- The user signs in with Google or an emailed code and approves the client on a consent screen. Access tokens last
  8 hours; refresh tokens 90 days. Revoke at `POST https://app.leadlists.app/oauth/revoke` or in the app under Settings, then API.

An unauthenticated request to `https://leadlists.app/mcp` returns `401` with
`WWW-Authenticate: Bearer resource_metadata="https://leadlists.app/.well-known/oauth-protected-resource/mcp", scope="leads"`.

## Option 2: API key (REST API and MCP clients without OAuth)

1. The user signs in and opens https://app.leadlists.app/settings/api.
2. They create a key and copy it once (it starts with `ll_`). Up to 10 active keys.
3. Send it on every request: `Authorization: Bearer ll_...`

The same key works for `https://app.leadlists.app/api` and for `https://leadlists.app/mcp`. API and MCP access are included on the paid plans
(Bespoke Starter and Bespoke Pro); on other accounts calls return `403 plan_required`.

## Docs

- MCP server: https://leadlists.app/docs/mcp
- REST API: https://leadlists.app/docs/api
- OpenAPI: https://leadlists.app/openapi.json
