# Authenticate a person or agent

Updated: 2026-08-31

A person or organisation owns the VibeCord account, accepts the applicable
terms and age requirements, and controls payment authority. An agent acts as a
delegated operator with a scoped, expiring token. The agent is not the legal
account owner and must not invent an identity or infer permission to spend.

## Current authentication flow

Autonomous legal account signup is not implemented. The device authorization
request and polling contracts, CLI commands, server start/poll endpoints, and
signed-in human decision routes now exist in source. The route remains
default-off and is not deployed, release-proven, or publicly available:

```sh
vibecord-ops auth device start \
  --client-name "Coding Agent" \
  --scopes ops:read,project:write,workload:write \
  --open --json
VIBECORD_DEVICE_CODE=<private-device-code> vibecord-ops auth device poll --json
```

Do not treat these source commands as a live signup or login path. When both
internal MCP and PAT feature gates are enabled, current internal dogfood uses
a browser-assisted token handoff:

```sh
vibecord-ops auth login --open --json
```

The command returns:

- `connectUrl`, normally `https://app.vibecord.dev/vc/cli-connect`;
- `fallbackConnectUrl`, used if the app route does not show the CLI connection
  page; and
- instructions for the signed-in account owner.

If those internal gates are off, the connect surface returns unavailable. Do
not describe that environment as agent-auth ready or attempt to bypass the
gate.

The account owner opens the URL in their authenticated VibeCord browser
session, selects **Issue CLI token**, and copies the token shown once into the
current shell or approved secret store. The page shows the token's expiry.

```sh
export VIBECORD_API_URL="https://app.vibecord.dev"
read -rsp "VIBECORD_TOKEN: " VIBECORD_TOKEN && export VIBECORD_TOKEN && printf '\n'
vibecord-ops auth whoami --json
```

PowerShell:

```powershell
$env:VIBECORD_API_URL = "https://app.vibecord.dev"
$secureToken = Read-Host "VIBECORD_TOKEN" -AsSecureString
$env:VIBECORD_TOKEN = [System.Net.NetworkCredential]::new("", $secureToken).Password
Remove-Variable secureToken
vibecord-ops auth whoami --json
```

Persistent operating-system credential storage is not implemented in the
current CLI. Clearing `VIBECORD_TOKEN` removes it from the current shell:

```sh
unset VIBECORD_TOKEN
```

PowerShell:

```powershell
Remove-Item Env:VIBECORD_TOKEN
```

## Account and agent boundary

An agent may:

- request the browser connection URL;
- explain the exact scopes and action it needs;
- pause while the account owner signs in and issues the token;
- use the token only for admitted VibeCord operations; and
- return a typed denial or human handoff when authority is missing.

An agent must not:

- accept terms or age declarations for another person;
- collect or store passwords, card details, provider credentials, bot tokens,
  runtime tokens, or unrelated secrets;
- reuse a token outside its audience, scope, project, or workload boundary;
- revoke another token without the account owner's action-time approval; or
- treat possession of a token as permission to incur uncapped spend.

## Failure handling

| Result | Next safe action |
| --- | --- |
| `not_authenticated` | Run `vibecord-ops auth login --open --json`, then let the signed-in account owner issue a scoped token. |
| `active_token_limit_reached` | Ask the account owner to review token metadata and approve revocation of one old CLI/API token. Do not delete one automatically. |
| Wrong account or workload | Stop. Ask the owner to select the correct account, project, and connected workload row. |
| Expired or rejected token | Clear it, repeat the browser handoff, and verify with `auth whoami`. |

The device-authorization server source preserves the same ownership boundary:
it produces an audience-bound, short-lived, revocable token only after a
signed-in person approves narrowed scopes. Production still requires the
durable migration, code-pepper configuration, organisation-workspace selection,
release, and clean-machine proof. Terms, age, account ownership, and payment
remain separate human decisions; an operable public flow remains unproven.

Read [PAYMENTS.md](./PAYMENTS.md) before any spend-bearing request.