# CLI Authentication (/docs/cli/authentication)



## Token lifecycle [#token-lifecycle]

`voidnet login` mints a machine token (`vnp-pub-*`, 30 days) through browser consent, then verifies it against the publisher API **before** storing anything. A mint that fails verification is rolled back (revoked), never kept. `login --token` verifies a console-issued token the same way and rejects garbage at the door.

`voidnet logout` revokes the token server-side first, then wipes local credentials. Revocation is confirmed — a logout that cannot reach the server fails loud instead of pretending.

## Scopes [#scopes]

Login grants read and verify scopes only:

| Granted at login                                         | Console only                  |
| -------------------------------------------------------- | ----------------------------- |
| `apps:read`, `apps:verify`, `metering:read`, `keys:read` | `apps:publish`, `keys:rotate` |

A `403 insufficient_scope` names the missing scope. Re-logging in never grants more — publish and key rotation stay in the console by server design.

## Profile and identity [#profile-and-identity]

Login stores a profile alongside the token: display name, publisher username, granted scopes, app binding, and expiry. Inspect it with:

```sh
voidnet profile
voidnet whoami
```

`whoami` without a profile says `You haven't logged in, run voidnet login first.` and exits 1.

## Where credentials live [#where-credentials-live]

| Source                          | Use                                        |
| ------------------------------- | ------------------------------------------ |
| `--publisher-token` flag        | Single command override (highest priority) |
| `VOIDNET_PUBLISHER_TOKEN` env   | CI and scripts                             |
| OS keychain                     | Workstations (stored by login/configure)   |
| `~/.config/voidnet/config.yaml` | Fallback when no keychain exists           |

Secrets are masked everywhere except the two once-only deliveries (key rotation, token creation). Never commit tokens; prefer keychain on workstations and short-lived tokens in CI.