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

# Paubox CLI authentication

> Log in, log out, and check credential status with the Paubox CLI. Keys are stored in your OS keychain, or read from PAUBOX_API_KEY in CI.

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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.