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

Check status

View your authentication status:

$ vapi auth status

Add another account

Add additional accounts without logging out:

$ vapi auth login

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
2 api_key: your-api-key
3 base_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

Separate environments

Agency workflow

Team collaboration

$ # 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
2 env:
3   VAPI_API_KEY: ${{ secrets.VAPI_PROD_KEY }}
4 
5 steps:
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

Token expired

If you see authentication errors:

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

Keychain access issues

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

Organization access

If you can’t access organization resources:

Verify organization membership in dashboard
Check account permissions
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 
7 To switch: `vapi auth switch <alias>`

Next steps

With authentication configured:

Create assistants: Build voice assistants
Initialize projects: Add Vapi to your codebase
Test webhooks: Debug locally with any account

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

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