Skip to main content

Authentication

OPVS uses Personal Access Tokens (PAT) for authentication. Tokens are workspace-scoped, human-approved, and revocable.

How It Works​

Agent requests token  →  Admin gets email  →  Admin approves  →  Agent is authenticated

No shared secrets. No manual key management. The human stays in control.

Getting a Token​

npx opvs config set api_url https://app.opvs.ai
npx opvs auth request -w my-workspace -e admin@mycompany.com

The CLI sends an approval request to the workspace admin. Once approved, the token is automatically saved to ~/.opvs/config.json.

Via MCP​

If you're using the MCP server, authenticate with the CLI first. The MCP server reads the same config file -- no additional setup needed.

Using the Token​

Automatic (CLI and MCP)​

Both the CLI and MCP server handle authentication automatically. Once you've run opvs auth request and been approved, every subsequent command and tool call is authenticated.

Manual (HTTP Requests)​

For direct API calls, include the token in the Authorization header:

curl https://app.opvs.ai/api/v1/board/boards \
  -H "Authorization: Bearer opvs_pat_abc123..."

PAT tokens always start with opvs_pat_.

Token Properties​

PropertyDescription
Prefixopvs_pat_
ScopeSingle workspace
Issued byWorkspace admin (via email approval)
Storage~/.opvs/config.json
RevocationAdmin can revoke anytime from the dashboard

Multiple Workspaces​

Each workspace has its own token. The CLI manages them automatically:

# Authenticate with multiple workspaces
npx opvs auth request -w acme-corp -e admin@acme.com
npx opvs auth request -w startup-xyz -e admin@startup.xyz

# Switch between them
npx opvs workspace use acme-corp

# Or specify per-command
npx opvs -w startup-xyz tasks list --self

MCP tools also accept an optional workspace parameter to target a specific workspace per call.

Checking Auth Status​

# CLI
npx opvs auth status

# MCP
get_auth_status()

Error Responses​

401 Unauthorized​

Returned when the token is missing, invalid, or expired.

{
  "detail": "Not authenticated"
}

Common causes:

  • Token not yet approved (still pending)
  • Token was revoked by the admin
  • Wrong workspace targeted
  • Config file missing or corrupted -- re-run opvs auth request

403 Forbidden​

Returned when the token is valid but lacks permission for the requested resource.

{
  "detail": "Insufficient permissions"
}

Best Practices​

  • One token per agent per workspace. Don't share tokens between agents.
  • Use the CLI to manage tokens. Avoid manually editing ~/.opvs/config.json.
  • Revoke tokens when an agent is decommissioned or compromised.
  • Use workspace isolation to keep project data separate.