Authentication

VirtuousAI supports multiple authentication methods to suit different use cases. This guide explains how authentication works and when to use each method.

Authentication Methods

OAuth2 / Web Session

For interactive users accessing VirtuousAI through a web browser, we use OAuth2 with WorkOS as our identity provider.

The flow works as follows:

1. User clicks "Sign In" in the web app
2. User is redirected to WorkOS for authentication
3. After successful login, WorkOS redirects back with an authorization code
4. The code is exchanged for access and refresh tokens
5. Sessions refresh automatically in the background

Sessions are managed automatically — tokens refresh in the background, and users remain logged in until they explicitly sign out.

Personal Access Tokens (PAT)

PATs are long-lived tokens for programmatic access. They're perfect for:

• CLI usage across machines
• CI/CD pipelines
• Scheduled scripts

Creating a PAT

vai tokens create "CI/CD Token" --expires-in-days 90
# ✓ Token created: vai_pat_abc123...
# ⚠ Store this token securely - it won't be shown again!

curl -X POST https://vai-dev.virtuousai.com/api/v1/access-tokens \
  -H "Authorization: Bearer $CURRENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Token", "expiresInDays": 90}'

Using a PAT

Include the token in the Authorization header:

curl -H "Authorization: Bearer vai_pat_abc123..." \
  https://vai-dev.virtuousai.com/api/v1/connections

Or set it as an environment variable for the CLI:

export VAI_API_KEY=vai_pat_abc123...
vai connections list

Device Flow (CLI Login)

The device flow enables CLI authentication without exposing credentials in the terminal.

The flow works as follows:

1. CLI requests a device code from the API
2. API returns a device code and verification URL
3. CLI displays the URL and code to the user
4. User opens the URL in their browser and enters the code
5. User approves the request
6. CLI polls the API and receives an access token

Using Device Flow

vai auth login
# Please visit: https://vai-dev.virtuousai.com/device
# And enter code: ABCD-1234
# Waiting for authorization...
# ✓ Successfully authenticated!

The CLI polls the API until you approve the request in your browser.

Multi-Organization Access

Users can belong to multiple organizations. The current organization context determines which data you can access.

Viewing Organizations

vai org list
# ID              NAME            ROLE
# org_abc123      Acme Corp       admin
# org_def456      Beta Inc        member

Switching Organizations

vai org use acme-corp
# ✓ Switched to organization: Acme Corp

Or specify per-request via header:

curl -H "Authorization: Bearer $TOKEN" \
     -H "X-Organization-Id: org_abc123" \
     https://vai-dev.virtuousai.com/api/v1/connections

Session Management

Viewing Active Sessions

vai sessions list
# ID              DEVICE          LAST ACTIVE      LOCATION
# ses_abc123      Chrome/Mac      2 minutes ago    San Francisco, CA
# ses_def456      vai-cli         1 hour ago       New York, NY

Revoking Sessions

Revoke a specific session:

vai sessions revoke ses_def456

Revoke all sessions (nuclear option):

vai sessions revoke-all --yes

Token Management

Viewing Tokens

vai tokens list
# ID              NAME            CREATED          LAST USED        EXPIRES
# tok_abc123      CI/CD Token     2026-01-15       2 hours ago      2026-04-15
# tok_def456      Local Dev       2026-01-20       never            2026-07-20

Revoking Tokens

vai tokens revoke tok_abc123
# ✓ Token revoked

Best Practices

Next Steps