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

# Authentication

> How to obtain and pass credentials to the Paubox Email API.

Every request to the Paubox Email API must include your API key in the `Authorization` header. Keys are generated per domain from the [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) page.

## Find your credentials

<Steps>
  <Step title="Open Email API Settings">
    Go to [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) and click the domain you want to send from.
  </Step>

  <Step title="Generate an API key">
    Click **Add API Key**, give it a description, and save. Copy the key immediately; it is displayed only once.
  </Step>

  <Step title="Note your endpoint username">
    Your API endpoint username appears on the same settings page. It forms the base URL for every request:

    ```
    https://api.paubox.net/v1/YOUR_USERNAME
    ```
  </Step>
</Steps>

## Pass credentials in requests

Include the `Authorization` header with every API call:

```bash theme={null}
curl --request POST \
  --url https://api.paubox.net/v1/YOUR_USERNAME/messages \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json'
```

### Bearer format (preferred)

```
Authorization: Bearer YOUR_API_KEY
```

### Legacy Token format (also accepted)

```
Authorization: Token token=YOUR_API_KEY
```

Both formats are accepted. New integrations should use Bearer.

## Key rotation

* Generate a new key before revoking an old one to avoid downtime.
* Each domain can have multiple active keys, which is useful for rotating across services independently.
* Revoke keys immediately if they are exposed or a team member with access leaves.

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager to inject credentials at runtime.

  ```bash theme={null}
  # Good
  export PAUBOX_API_KEY=your_api_key
  curl -H "Authorization: Bearer $PAUBOX_API_KEY" ...

  # Bad — do not do this
  curl -H "Authorization: Bearer sk_live_abc123..." ...
  ```
</Warning>