VruumVruum

Auth

How vruum authenticates — personal access tokens, the VRUUM_TOKEN environment variable, operator --for-company scoping, and the Bearer model.

vruum authenticates with a personal access token (PAT, vk_live_…). Generate one in the Vruum web app under Settings → API tokens. The same token authorizes both surfaces — the CLI and the MCP server — and neither can exceed your access: every call is authorized server-side by your token exactly as a normal user's would be.

Logging in

# Interactive — prompts for the token (hidden) and stores it in ~/.vruum
vruum login
# Non-interactive — pass it or pipe it in
vruum login --token vk_live_xxx
echo "vk_live_xxx" | vruum login

vruum whoami          # confirm who you are authenticated as
vruum logout          # remove stored credentials

login, logout, init, and the auth commands (whoami aside) are local-CLI only — they manage host credentials/config and are blocked from the server-side vruum_exec path, which injects your token for you.

Environment variables

VariablePurpose
VRUUM_TOKENPAT to use (overrides the stored credentials file)
VRUUM_API_URLOverride the API base URL (default https://api.vruum.ai)
VRUUM_CONFIG_DIROverride the config/credentials directory (default ~/.vruum)

VRUUM_TOKEN makes the CLI fully stateless — ideal for CI and agent harnesses, where there is no vruum login step:

VRUUM_TOKEN=vk_live_xxx vruum deal list --json

The Bearer model

The MCP server is Bearer-authed: vruum init writes a static Authorization: Bearer <token> MCP config rather than relying on interactive OAuth (which drops hosted MCP connections mid-session). The server-side vruum_exec tool runs the bundled CLI under the token the server injects — which is why the host-override flag --api-url (and VRUUM_API_URL) is rejected there: it would redirect the authenticated call to an arbitrary host and exfiltrate your token. See MCP for the full vruum_exec contract.

Operating on behalf of a company — --for-company

Operators managing multiple tenants scope any command to one company:

vruum --for-company <company_id_or_exact_name> deal list
  • On the CLI, --for-company is sent as the X-Company-Id header.
  • Over MCP, the same intent is the for_company parameter. Resolution is by UUID or case-insensitive EXACT company-name match — partial/substring matches are NOT supported (an ambiguous name raises 400).
  • Access is membership-enforced server-side: the value resolves to a user_company_id and the caller's membership in company_users is verified. A 403 means the value matched no company or the caller is not a member of it. --for-company does not grant automatic operator powers — you get this access by being a member of each client company, the same row that grants any normal user access.

See also