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

> Store and manage Paubox API credentials with the CLI.

The CLI authenticates against authenticated Paubox endpoints (such as the [Paubox Email API](/email-api)) using your API key and endpoint username. Run `paubox auth login` once and your credentials are stored securely; you won't need to pass them on every command.

To get your API key and endpoint username, go to [Paubox Email API > Settings](https://next.paubox.com/emailapi/settings) or follow the [Quickstart guide](/email-api/quickstart).

## Commands

| Command              | Description                                                      |
| :------------------- | :--------------------------------------------------------------- |
| `paubox auth login`  | Prompt for API username and key, validate, and store credentials |
| `paubox auth logout` | Remove stored credentials                                        |
| `paubox auth status` | Show whether credentials are currently stored                    |

## auth login

```bash theme={null}
paubox auth login
```

```
? Paubox API username: your_endpoint_username
? Paubox API key: ********************************
✓ Credentials verified and saved.
```

The CLI validates your credentials against the Paubox API before saving them. If validation fails, nothing is stored and an error is shown.

## auth logout

```bash theme={null}
paubox auth logout
```

```
✓ Credentials removed.
```

This removes the stored API key and username from wherever they were saved (keychain or config file).

## auth status

```bash theme={null}
paubox auth status
```

```
✓ Logged in as your_endpoint_username
```

If no credentials are stored:

```
✗ Not logged in. Run `paubox auth login` to authenticate.
```

## Where credentials are stored

| Platform                  | Storage location                                       |
| :------------------------ | :----------------------------------------------------- |
| macOS                     | macOS Keychain                                         |
| Windows                   | Windows Credential Vault                               |
| Linux (with libsecret)    | Secret Service (GNOME Keyring / KWallet)               |
| Linux (without libsecret) | `~/.config/paubox/config.json` with `0600` permissions |

<Warning>
  If your system falls back to file-based storage, never commit `~/.config/paubox/config.json` to source control. Add it to your `.gitignore` if your home directory is under version control.
</Warning>

<Note>
  In CI environments, set credentials via environment variables instead of running `auth login`. The CLI reads `PAUBOX_API_KEY` and `PAUBOX_API_USERNAME` if present, and these take precedence over stored credentials.
</Note>

<Note>
  `paubox forms get` and `paubox forms submit` call public Paubox Forms endpoints and do not require `paubox auth login`.
</Note>