Authentication management

Overview

The Vapi CLI supports sophisticated authentication management, allowing you to work with multiple accounts, organizations, and environments seamlessly. This is perfect for developers who work across different teams, manage client accounts, or need to switch between production and staging environments.

In this guide, you’ll learn to:

  • Authenticate with your Vapi account
  • Manage multiple accounts simultaneously
  • Switch between organizations and environments
  • Configure API keys and tokens

Quick start

1

Initial login

Authenticate with your primary account:

$vapi login

This opens your browser for secure OAuth authentication.

2

Check status

View your authentication status:

$vapi auth status
3

Add another account

Add additional accounts without logging out:

$vapi auth login
4

Switch accounts

Switch between authenticated accounts:

$vapi auth switch production

Authentication methods

The default authentication method uses OAuth for maximum security:

$vapi login
># Opens browser for authentication
># Securely stores tokens locally

Benefits:

  • No manual API key handling
  • Automatic token refresh
  • Secure credential storage
  • Organization access management

API key authentication

For CI/CD or scripting, use API keys:

$# Via environment variable
>export VAPI_API_KEY=your-api-key
>vapi assistant list
>
># Via command flag
>vapi assistant list --api-key your-api-key

Configuration file

Store API keys in configuration:

1# ~/.vapi-cli.yaml
2api_key: your-api-key
3base_url: https://api.vapi.ai # Optional custom endpoint

Multi-account management

Understanding accounts

Each authenticated account includes:

  • User identity - Your email and user ID
  • Organization - The Vapi organization you belong to
  • API access - Permissions and API keys
  • Environment - Production, staging, or custom

Viewing accounts

List all authenticated accounts:

$vapi auth status

Output:

🔐 Vapi Authentication Status
Active Account:
✓ Email: john@company.com
✓ Organization: Acme Corp (org_abc123)
✓ Environment: Production
✓ API Key: sk-prod_****efgh
Other Accounts:
• jane@agency.com - ClientCo (org_xyz789) [staging]
• john@personal.com - Personal (org_def456) [production]
Total accounts: 3

Adding accounts

Add accounts without affecting existing ones:

$# Add another account
>vapi auth login
>
># You'll be prompted to:
># 1. Open browser for authentication
># 2. Choose an account alias (e.g., "staging", "client-a")
># 3. Confirm organization access

Switching accounts

Switch between accounts instantly:

$# Switch by alias
>vapi auth switch staging
>
># Switch by email
>vapi auth switch jane@agency.com
>
># Interactive selection
>vapi auth switch
># Shows menu of available accounts

Account aliases

Assign meaningful aliases to accounts:

$# During login
>vapi auth login --alias production
>
># Update existing
>vapi auth alias john@company.com production
>
># Use aliases
>vapi auth switch production

Common workflows

Development vs production

$# Development work
>vapi auth switch dev
>vapi assistant create --name "Test Assistant"
>
># Production deployment
>vapi auth switch prod
>vapi assistant create --name "Customer Support"

Account information

Get detailed information about current account:

$vapi auth whoami

Output:

1{
2 "user": {
3 "id": "user_abc123",
4 "email": "john@company.com",
5 "name": "John Doe"
6 },
7 "organization": {
8 "id": "org_abc123",
9 "name": "Acme Corp",
10 "plan": "enterprise"
11 },
12 "permissions": [
13 "assistants:read",
14 "assistants:write",
15 "calls:create",
16 "billing:view"
17 ]
18}

Token management

View and manage API tokens:

$# View current token (masked)
>vapi auth token
>
># Show full token (careful!)
>vapi auth token --show
>
># Refresh token
>vapi auth refresh

Security best practices

Credential storage

The CLI stores credentials securely:

  • macOS: Keychain
  • Linux: Secret Service API / keyring
  • Windows: Credential Manager

Environment isolation

Keep environments separate:

$# Never mix environments
>vapi auth switch prod
>vapi assistant list # Production assistants
>
>vapi auth switch dev
>vapi assistant list # Development assistants

CI/CD integration

For automated workflows:

1# GitHub Actions example
2env:
3 VAPI_API_KEY: ${{ secrets.VAPI_PROD_KEY }}
4
5steps:
6 - name: Deploy Assistant
7 run: |
8 vapi assistant create --file assistant.json

Revoking access

Remove accounts when no longer needed:

$# Logout from current account
>vapi auth logout
>
># Logout from specific account
>vapi auth logout jane@agency.com
>
># Logout from all accounts
>vapi auth logout --all

Advanced features

Custom API endpoints

For on-premise or custom deployments:

$# Login to custom endpoint
>vapi login --base-url https://vapi.company.internal
>
># Or configure in file
>echo "base_url: https://vapi.company.internal" >> ~/.vapi-cli.yaml

Service accounts

For server applications:

$# Create service account in dashboard
># Then configure:
>export VAPI_API_KEY=service_account_key
>export VAPI_ORG_ID=org_abc123

Proxy configuration

For corporate environments:

$# HTTP proxy
>export HTTP_PROXY=http://proxy.company.com:8080
>export HTTPS_PROXY=http://proxy.company.com:8080
>
># SOCKS proxy
>export ALL_PROXY=socks5://proxy.company.com:1080

Troubleshooting

Configure default browser:

$# macOS
>export BROWSER="Google Chrome"
>
># Linux
>export BROWSER=firefox
>
># Windows
>set BROWSER=chrome

If you see authentication errors:

$# Refresh current token
>vapi auth refresh
>
># Or re-login
>vapi login

For credential storage problems:

$# macOS: Reset keychain access
>security unlock-keychain
>
># Linux: Install keyring
>sudo apt-get install gnome-keyring
>
># Use file storage instead
>vapi config set storage file

If you can’t access organization resources:

  1. Verify organization membership in dashboard
  2. Check account permissions
  3. Re-authenticate:
$vapi auth logout
>vapi login

Best practices

Account naming

Use clear, consistent aliases:

$# Good aliases
>vapi auth login --alias prod-acme
>vapi auth login --alias dev-personal
>vapi auth login --alias staging-client
>
># Avoid unclear aliases
>vapi auth login --alias test1
>vapi auth login --alias new

Regular maintenance

Keep your authentication clean:

$# Monthly review
>vapi auth status
>
># Remove unused accounts
>vapi auth logout old-client@example.com
>
># Update tokens
>vapi auth refresh --all

Team documentation

Document account structure for your team:

1## Vapi Accounts
2
3- `prod`: Production (org_abc123)
4- `staging`: Staging environment (org_abc124)
5- `dev`: Shared development (org_abc125)
6
7To switch: `vapi auth switch <alias>`

Next steps

With authentication configured:


Security tip: Always use OAuth login for interactive use and API keys only for automation. Never commit API keys to version control!