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

# Authentication

> OAuth authentication for the LeadMagic MCP server

The LeadMagic MCP server uses OAuth. Add `https://mcp.leadmagic.io/mcp` in a compatible AI client, then sign in when the client opens the LeadMagic authorization flow.

## How Authentication Works

Your AI client discovers the protected resource metadata from `mcp.leadmagic.io`, sends you through LeadMagic sign-in, and receives an access token for MCP tool calls.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://mcp.leadmagic.io/mcp
Authorization: Bearer <access_token>
Content-Type: application/json
```

<CardGroup cols={3}>
  <Card title="OAuth sign-in" icon="right-to-bracket">
    Your client sends you through a LeadMagic authorization flow.
  </Card>

  <Card title="Bearer tokens" icon="key">
    MCP requests use OAuth bearer tokens rather than copied API keys.
  </Card>

  <Card title="Credit-Based" icon="coins">
    Each tool call deducts credits from your account balance.
  </Card>
</CardGroup>

## Connect

<Steps>
  <Step title="Add the MCP server">
    Use `https://mcp.leadmagic.io/mcp` as the server URL in your AI client.
  </Step>

  <Step title="Authorize">
    Complete the LeadMagic sign-in flow when your AI client prompts you.
  </Step>

  <Step title="Test the connection">
    Ask your AI assistant to check your LeadMagic credits.
  </Step>
</Steps>

## Discovery metadata

<ResponseField name="Protected resource" type="URL">
  `https://mcp.leadmagic.io/.well-known/oauth-protected-resource`
</ResponseField>

<ResponseField name="Authorization server" type="URL">
  `https://mcp.leadmagic.io/.well-known/oauth-authorization-server`
</ResponseField>

<ResponseField name="MCP endpoint" type="URL">
  `https://mcp.leadmagic.io/mcp`
</ResponseField>

## Security Best Practices

<AccordionGroup>
  <Accordion title="Do not paste OAuth secrets into docs or chat" icon="lock">
    OAuth client secrets are shown once when generated. If a secret is exposed, rotate it before using the integration.
  </Accordion>

  <Accordion title="Use the OAuth flow when available" icon="shield">
    Prefer clients that can complete OAuth for remote MCP servers. Avoid static token or header configurations unless your workspace explicitly requires them.
  </Accordion>

  <Accordion title="Revoke access if compromised" icon="arrows-rotate">
    If an OAuth client or token is exposed, revoke or rotate it from your LeadMagic app settings.
  </Accordion>

  <Accordion title="Monitor usage" icon="chart-line">
    Check your credit consumption regularly. Use `check_credit_balance` for balance checks, `get_account_analytics` for usage and rate-limit headroom, or visit your [dashboard](https://app.leadmagic.io).
  </Accordion>
</AccordionGroup>

## Authentication Errors

| Error              | Cause                           | Solution                                                                            |
| ------------------ | ------------------------------- | ----------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid bearer token | Reconnect the MCP server and complete OAuth sign-in                                 |
| `403 Forbidden`    | No credits remaining            | [Purchase credits](https://app.leadmagic.io/settings/billing) or check your balance |
| `invalid_token`    | Token expired or revoked        | Reauthorize the MCP connection                                                      |

<Tip>
  Test your authentication by asking your AI assistant to "check my LeadMagic credits." The `check_credit_balance` tool is free and confirms your connection is working.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="gear" href="/docs/mcp/setup">
    Configure your MCP client.
  </Card>

  <Card title="Credits & Pricing" icon="coins" href="/docs/v1/credits">
    Understand credit costs and manage your balance.
  </Card>
</CardGroup>