# Authentication

Set up scoped VentilatePro tokens, verify project access, understand keyring and file storage, and revoke credentials for CLI and MCP workflows.

Canonical: https://ventilatepro.com/exam/cli/auth/

Documentation version: VentilatePro CLI 0.8.4

## Token lifecycle

1. Create the token in the web UI

   Open VentilatePro Account Settings and create a CLI token. The raw token is shown once, so copy it immediately.
2. Log in from your machine

   ```text
   ventilatepro auth login
   ```

   ```text
   ventilatepro auth login --token-prompt-visible
   ```

   ```text
   Get-Clipboard | ventilatepro auth login --token-stdin
   ```
3. Verify the token

   The CLI validates credentials through the authenticated identity endpoint before saving them.

   ```text
   ventilatepro auth whoami
   ```

## Token presets

Create a separate token for each workstation or agent host, and choose the smallest preset that supports the intended workflow.

| Preset | Best for | Access model |
| --- | --- | --- |
| `notes-only` | Field and coordination notes | Project discovery plus note read/create/update. |
| `assistant-read-calc` | Read-oriented tools | Entities, systems, calculations, and design-day reads/runs. |
| `editor` | Human terminal editing | Read/calc plus entity, import, schedule, control, and note writes. |
| `agent-editor` | Local MCP agents | Guarded full-workflow access including QC, notifications, exports, and team lookup. |

## Auth commands

Status

```text
ventilatepro auth status
```

```text
ventilatepro auth status --json
```

Identity

```text
ventilatepro auth whoami
```

Logout

```text
ventilatepro auth logout
```

## Local storage

- Base URL and non-secret settings are stored in the OS config directory.
- Tokens are stored in the OS keyring when a supported backend is available.
- If keyring is unavailable, the token falls back to plaintext in `config.json`. Protect that directory with OS permissions and exclude it from shared folders, backups available to others, and source control.
- `auth logout` deletes only local credentials; it does not revoke the server token.

## Windows terminals

- The default login prompt hides input, so pasted characters do not appear on screen.
- Prefer the hidden prompt or `--token-stdin`. The fallback `--token-prompt-visible` displays the secret on screen; do not use it in a recorded or shared terminal. Avoid `--token` in interactive shells because command history and process inspection can expose it.
- For copy-paste workflows, pipe the token from stdin with `--token-stdin`.
- PowerShell example: `Get-Clipboard | ventilatepro auth login --token-stdin`

## Security model

- CLI tokens authenticate as bearer tokens in the `Authorization` header.
- Raw tokens are only shown at creation time in the web UI.
- Do not place raw tokens in source control, MCP JSON, agent prompts, screenshots, or logs.
- Tokens never bypass project membership, web-app permissions, validation, or MCP confirmation guardrails.
- Revocation is managed server-side in VentilatePro Account Settings.
- Use a new token if an old one is lost or copied to the wrong machine.

[Open account settings](https://ventilatepro.com/hvac/?view=account-settings)