> ## 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. Run `paubox auth login` once and your API key is stored securely; you won't need to pass it on every command.

Follow the [Paubox Email API Quickstart Guide](/email-api/quickstart) to get your API key.

## Commands

| Command              | Description                                     |
| :------------------- | :---------------------------------------------- |
| `paubox auth login`  | Prompt for your API key, validate, and store it |
| `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 key: ********************************
✓ API key verified and saved.
```

The CLI validates your API key against the Paubox API before saving it. 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 from wherever it was saved (keychain or config file).

## auth status

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

```
✓ Logged in. API key is valid for sending domain yourclinic.com.
```

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 your API key via an environment variable instead of running `auth login`. The CLI reads `PAUBOX_API_KEY` if present, and it takes 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>