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

# Authentication

> How OAuth sign-in and account authorization work for the Enrichley MCP server.

The Enrichley MCP server uses OAuth 2.1 with PKCE to authorize AI clients. You sign in once per client, and your Enrichley API key stays server-side — your AI assistant never sees it.

<CardGroup cols={3}>
  <Card title="OAuth-protected" icon="lock">
    Industry-standard OAuth 2.1 with PKCE. Your AI client receives a short-lived token, not your API key.
  </Card>

  <Card title="Server-side credentials" icon="shield-halved">
    Your account credential is resolved server-side, never exposed to the AI client or returned in tool responses.
  </Card>

  <Card title="Credit-based" icon="coin">
    Validation calls deduct from the same credit balance as the Enrichley REST API.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Your AI client requests access.">
    When you connect Enrichley to a new client, it opens a browser window to begin the OAuth flow.
  </Step>

  <Step title="You sign in to Enrichley.">
    Sign in to your Enrichley account in the browser.
  </Step>

  <Step title="The server checks account readiness.">
    The server confirms your Enrichley account, plan, and API credential are ready before completing the flow.
  </Step>

  <Step title="The client receives an OAuth token.">
    Your AI client only receives a short-lived OAuth token — never the API key itself.
  </Step>

  <Step title="Tool calls use server-side authorization.">
    When your assistant calls a tool, the server refreshes the backend grant, calls the Enrichley API on your behalf, and returns the result.
  </Step>
</Steps>

## Account requirements

You need an Enrichley account on a paid plan. The MCP server resolves your account credential server-side; you do not paste an API key into the MCP authorization flow.

## Scopes

When you authorize an AI client, you grant the following scopes:

| Scope            | What it allows                                     |
| ---------------- | -------------------------------------------------- |
| `account.read`   | Read your remaining credits and rate-limit window. |
| `validation.run` | Validate email addresses (consumes credits).       |

Both scopes are requested by default. The same scopes apply to every connected client.

## Security best practices

<Warning>
  Treat your API key like a password. Never paste it into a chat, share it in screenshots, or commit it to a public repo.
</Warning>

* **Use your own paid Enrichley account.** Usage and credits are billed to the signed-in account.
* **Rotate your key if you think it has leaked.** Generating a new key on your [Enrichley profile](https://app.enrichley.io/profile) immediately invalidates the old one.
* **Disconnect MCP clients you no longer use.** Each client holds its own OAuth token; revoke them when you stop using a device or workspace.

## Disconnecting and revoking access

You have three ways to revoke access:

1. **Disconnect inside your AI client.**
   * **Claude Code:** run `/mcp` and clear authentication for `enrichley`.
   * **Cursor:** disable the Enrichley server in the MCP panel.
   * **MCP Inspector:** close the session.
2. **Rotate your Enrichley API key.** Generate a new key on your [Enrichley profile](https://app.enrichley.io/profile). The old key is revoked immediately, and existing MCP clients may need to reconnect.
3. **Contact support.** Email [support@enrichley.io](mailto:support@enrichley.io) if you need help revoking access for a specific client or session.

## Authentication errors

If something goes wrong during connection or a tool call, you may see one of these:

| Error                  | What it means                                                                | What to do                                                           |
| ---------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `Account not eligible` | The signed-in account does not have an active plan or ready API credential.  | Sign in with the right account or upgrade your plan, then reconnect. |
| `Credential not ready` | The account API credential is missing, disabled, or temporarily unavailable. | Check your Enrichley profile, then reconnect the client.             |
| `Session expired`      | Your AI client's OAuth token has expired.                                    | Reconnect the client to refresh the token.                           |
| `Unauthorized`         | The client did not include a valid token.                                    | Run the setup flow again for that client.                            |

## Next steps

<CardGroup cols={2}>
  <Card title="Setup Guide" icon="gear" href="/mcp/setup">
    Connect the MCP server to your AI client.
  </Card>

  <Card title="Tools Reference" icon="wrench" href="/mcp/tools">
    See what each tool does and how credits work.
  </Card>
</CardGroup>