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

# Authentication

> Learn how to authenticate your API requests

## Overview

The Stover API supports two authentication modes:

| Mode              | Use Case                      | Authentication         |
| ----------------- | ----------------------------- | ---------------------- |
| **Authenticated** | Server-to-server integrations | API Key (Bearer token) |
| **Public**        | Lead capture forms            | None (rate limited)    |

## Authenticated Mode

Use authenticated mode for server-side integrations.

### API Key Format

```
stover_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Making Requests

Include your API key in the `Authorization` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.stover.app/v1/contacts \
    -H "Authorization: Bearer stover_pk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"first_name": "Jane", "last_name": "Doe", "email": "jane@example.com"}'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.stover.app/v1/contacts', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer stover_pk_your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'jane@example.com'
    })
  });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.stover.app/v1/contacts',
      headers={
          'Authorization': 'Bearer stover_pk_your_api_key',
          'Content-Type': 'application/json'
      },
      json={
          'first_name': 'Jane',
          'last_name': 'Doe',
          'email': 'jane@example.com'
      }
  )
  ```
</CodeGroup>

### Getting an API Key

1. Log in to your [Stover Dashboard](https://dashboard.stover.app)
2. Navigate to **Settings** > **API Keys**
3. Click **Generate New Key**
4. Copy and securely store your API key

<Warning>
  API keys are only shown once. If you lose your key, you'll need to generate a new one.
</Warning>

## Public Mode

Public mode allows contact creation from websites without exposing API keys.

### When to Use

* Contact forms on your website
* Landing page lead capture
* Newsletter signup forms

### Limits

| Limit        | Value                  |
| ------------ | ---------------------- |
| Rate limit   | 20 requests/min per IP |
| Payload size | 50KB max               |

### Making Requests

Omit the `Authorization` header:

```javascript theme={null}
const response = await fetch('https://api.stover.app/v1/contacts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    first_name: 'Jane',
    last_name: 'Doe',
    email: 'jane@example.com',
    utm_source: 'website'
  })
});
```

## Error Codes

| Status | Description                |
| ------ | -------------------------- |
| 401    | Missing or invalid API key |
| 403    | Insufficient permissions   |
| 429    | Rate limit exceeded        |

## Best Practices

<CardGroup cols={2}>
  <Card title="Never expose API keys" icon="eye-slash">
    Use public mode for browser requests.
  </Card>

  <Card title="Use environment variables" icon="gear">
    Store keys in env vars, not source code.
  </Card>

  <Card title="Rotate keys regularly" icon="rotate">
    Generate new keys periodically.
  </Card>

  <Card title="Use HTTPS only" icon="lock">
    Always use HTTPS for requests.
  </Card>
</CardGroup>