# Authentication

> How a client signs in to HeyLead's MCP server: OAuth 2.1 with PKCE and dynamic client registration, the outreach:read and outreach:write scopes, one-hour access tokens with 90-day refresh, and how to revoke.

This is the Markdown twin of https://heylead.dev/docs/auth (the page, in text). Index for agents: https://heylead.dev/llms.txt

The hosted server at `https://heylead.dev/mcp` uses OAuth 2.1. Your client opens the browser, you sign in with Google and choose a workspace on the consent page, and the client keeps a token. You never paste a password or a token into a chat.

## Discovery

- Protected resource: `https://heylead.dev/.well-known/oauth-protected-resource`
- Authorization server: `https://heylead.dev/.well-known/oauth-authorization-server`

The authorization server metadata names the endpoints: `/oauth/authorize`, `/oauth/token`, `/oauth/register` (dynamic client registration, so a client needs no pre-shared id) and `/oauth/revoke`. PKCE with `S256` is required; the response type is `code`; grants are `authorization_code` and `refresh_token`.

## Scopes

| Scope | What it allows |
| --- | --- |
| `outreach:read` | Read campaigns, contacts, replies, results and status. A read-only connection can draft and show but never send. |
| `outreach:write` | Create and change campaigns, approve messages, send as you, launch and stop. |

## Token life

An access token lives one hour and is bound to this server. The refresh token lives 90 days; your client refreshes without asking you again. An authorization code lives 60 seconds.

## Revoking

Revoke a client from HeyLead Settings in the dashboard, or through `/oauth/revoke`. A revoked refresh token stops the client at the next refresh.

## The local client

The Python client ( `uvx heylead`) talks to the hosted backend with a private setup message from Settings → Integrations → Chat client → Local Python client; it contains a sign-in token, so paste it only into your own agent. This path does not use OAuth. See [Self-hosting](https://heylead.dev/docs/self-hosted).