> ## 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

> Secure your API requests with API key authentication

The LeadMagic API uses **API key authentication** to secure all requests. Your API key must be included in the header of every request.

## Getting Your API Key

<Steps>
  <Step title="Log in to LeadMagic">
    Visit [app.leadmagic.io](https://app.leadmagic.io/sign-in) and sign in to
    your account.
  </Step>

  <Step title="Navigate to Account Settings">
    Click on your profile icon and select "Account Profile" or "API Keys".
  </Step>

  <Step title="Copy your API Key">
    Your API key will be displayed. Click to copy it to your clipboard.

    <Warning>
      Treat your API key like a password. Never share it publicly.
    </Warning>
  </Step>
</Steps>

## Using Your API Key

Include your API key in the `X-API-Key` header of every request:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST 'https://api.leadmagic.io/v1/people/email-validation' \
    -H 'Content-Type: application/json' \
    -H 'X-API-Key: YOUR_API_KEY' \
    -d '{"email": "test@example.com"}'
  ```

  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch(
    "https://api.leadmagic.io/v1/people/email-validation",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.LEADMAGIC_API_KEY,
      },
      body: JSON.stringify({ email: "test@example.com" }),
    },
  );
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  import requests

  response = requests.post(
      'https://api.leadmagic.io/v1/people/email-validation',
      headers={
          'Content-Type': 'application/json',
          'X-API-Key': os.environ['LEADMAGIC_API_KEY']
      },
      json={'email': 'test@example.com'}
  )
  ```
</CodeGroup>

## Authentication Errors

If your API key is missing or invalid, you'll receive a `401 Unauthorized` response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errors": [
    {
      "type": "https://api.leadmagic.io/errors/invalid_api_key",
      "title": "Invalid API key. The key does not exist or is incorrect.",
      "status": 401,
      "code": "invalid_api_key"
    }
  ],
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-05T12:00:00.000Z"
  }
}
```

<AccordionGroup>
  <Accordion title="Common authentication issues" icon="circle-exclamation">
    | Issue                 | Solution                                                        |
    | --------------------- | --------------------------------------------------------------- |
    | Missing header        | Ensure `X-API-Key` header is included                           |
    | Header name variation | Header names are case-insensitive; use `X-API-Key` as canonical |
    | Invalid key           | Verify your key in the dashboard                                |
    | Expired key           | Regenerate your API key                                         |
  </Accordion>
</AccordionGroup>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="terminal">
    Store your API key in environment variables, not in your code.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    export LEADMAGIC_API_KEY="your_key_here"
    ```
  </Card>

  <Card title="Server-Side Only" icon="server">
    Never expose your API key in client-side JavaScript or mobile apps.
  </Card>

  <Card title="Use Secrets Managers" icon="vault">
    For production, use AWS Secrets Manager, HashiCorp Vault, or similar.
  </Card>

  <Card title="Rotate Regularly" icon="rotate">
    Regenerate your API key periodically and if you suspect compromise.
  </Card>
</CardGroup>

<Warning>
  **When team members leave:** Always regenerate your API key when employees with access leave your organization. This prevents unauthorized access.
</Warning>

## Checking Your Credits

<Tip>
  See the [Credits & Pricing](/docs/v1/credits) page for details on monitoring your balance, the [Check Credits endpoint](/docs/v1/reference/check-credits), and subscription plans.
</Tip>

## Regenerating Your API Key

If you need to regenerate your API key:

<Steps>
  <Step title="Go to Account Settings">
    Navigate to your Account Profile in the LeadMagic dashboard.
  </Step>

  <Step title="Click Regenerate">
    Find the API Key section and click "Regenerate Key".
  </Step>

  <Step title="Update your applications">
    Replace the old key in all your applications with the new one.

    <Warning>
      The old key will stop working immediately after regeneration.
    </Warning>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Making API Calls" icon="code" href="/docs/v1/making-api-calls">
    Learn the basics of making requests to our API.
  </Card>

  <Card title="Email Validation" icon="envelope-circle-check" href="/docs/v1/reference/email-validation">
    Try our most popular endpoint.
  </Card>
</CardGroup>