Authentication Issues

TL;DR

CMDOP authentication issues include invalid API keys, expired tokens, permission denied errors, and OAuth failures. Valid API keys start with cmd_ prefix. Run cmdop auth status to check token status, cmdop login to re-authenticate, or cmdop login --device-code for headless environments. Tokens are stored in ~/.cmdop/auth.json and should have 600 file permissions.

How do I fix an invalid API key?

What are the symptoms?


Error: invalid API key


Error: UNAUTHENTICATED

How do I diagnose an invalid API key?


# Check if key is set
echo $CMDOP_API_KEY
 
# Verify key format (should start with cmd_)
echo $CMDOP_API_KEY | head -c 10

How do I fix an invalid API key?

Check Key Format

Valid API keys look like:


cmd_acme_a1b2c3d4e5f6...

If your key doesn’t match:

Generate new key in dashboard
Or use CLI: cmdop auth create-key --name "my-key"

Create New Key


# Login first
cmdop login
 
# Create new key
cmdop auth create-key --name "script"

Copy the output - keys are shown only once.

Verify Key Works


# Test with API
curl -H "Authorization: Bearer $CMDOP_API_KEY" \
  https://api.cmdop.com/v1/machines

How do I fix an expired token?

What are the symptoms?


Error: token expired

How do I re-authenticate?


# Re-authenticate
cmdop logout
cmdop login

How do I check token expiration?


cmdop auth status

Output:


✓ Authenticated as: [email protected]
✓ Token expires: 2026-03-14

How do I fix permission denied errors?

What are the symptoms?


Error: permission denied


Error: PERMISSION_DENIED

What causes permission denied errors?

Not a member of workspace
Insufficient role
Machine not in workspace
API key lacks permission

How do I diagnose permission issues?


# Check current workspace
cmdop workspace current
 
# List your workspaces
cmdop workspace list
 
# Check your role
cmdop workspace members | grep $(whoami)

How do I fix permission denied errors?

Switch Workspace


# List available
cmdop workspace list
 
# Switch
cmdop workspace use <correct-workspace>

Request Access

Contact workspace admin to:

Invite you as member
Upgrade your role

API Key Permissions

If using API key, check permissions:


cmdop auth list-keys

Create key with correct permissions:


# Full access
cmdop auth create-key --name "admin"
 
# Read-only
cmdop auth create-key --name "readonly" \
  --permissions sessions:read,machines:read

How do I fix OAuth failures?

What are the symptoms?


Error: OAuth callback failed

or browser doesn’t open

How do I fix OAuth authentication?

Browser Doesn’t Open


# Manually open URL
cmdop login
 
# Copy the URL shown and open in browser

Callback Failed

Check browser didn’t block popup
Try different browser
Check corporate proxy

CLI in Container/SSH


# Use device flow
cmdop login --device-code

This shows a code to enter at cmdop.com/device.

How do I fix Unix socket permission denied errors?

What are the symptoms in local mode?


Error: permission denied (socket)

Why does this happen?

Local connections use Unix socket with UID verification. The connecting user must match the agent’s owner.

How do I diagnose socket permission issues?


# Check socket ownership
ls -l /tmp/cmdop-*.sock
 
# Check your UID
id

How do I fix socket permission errors?

Run as same user who started agent:


# If agent runs as 'deploy'
sudo -u deploy cmdop terminal localhost

Or restart agent as your user:


pkill -f "cmdop connect"
cmdop connect

When should I use API key vs OAuth?

When should I use OAuth?

Interactive CLI usage
Development
Personal access

When should I use an API key?

CI/CD pipelines
Scripts
Server automation

What are API key best practices?


# Name keys descriptively
cmdop auth create-key --name "github-actions-deploy"
 
# Set expiration
cmdop auth create-key --name "temp" --expires 7d
 
# Minimal permissions
cmdop auth create-key --name "readonly" \
  --permissions machines:read,sessions:read

How does two-factor authentication work?

What happens when 2FA is enabled?

When using cmdop login:

Browser opens
Enter credentials
Enter 2FA code
Callback completes

Does 2FA affect API keys?

API keys bypass 2FA after creation. To require 2FA:

Use OAuth for all access
Or implement application-level checks

How do I fix SSO issues?

Why is SAML not working?

Contact your IT admin to verify:

SAML IdP configured
User provisioned
Correct attributes mapped

How do I bypass misconfigured SSO?

If SSO is misconfigured:


# Try direct OAuth (if allowed)
cmdop login --provider google

Where are tokens stored?

What are the token storage locations?

Platform	Location
macOS	`~/.cmdop/auth.json`
Linux	`~/.cmdop/auth.json`
Windows	`%APPDATA%\cmdop\auth.json`

How do I fix a corrupted token?


# Remove and re-auth
rm ~/.cmdop/auth.json
cmdop login

How do I secure token file permissions?


# Check permissions
ls -la ~/.cmdop/auth.json
 
# Fix if needed (should be 600)
chmod 600 ~/.cmdop/auth.json

How do I revoke sessions?

How do I revoke all sessions?


# Revoke current device
cmdop logout
 
# Revoke all devices (web dashboard)
# Settings > Security > Revoke All Sessions

How do I revoke an API key?


# List keys
cmdop auth list-keys
 
# Revoke specific key
cmdop auth revoke-key cmd_acme_xxx

How do I debug authentication issues?


# Verbose auth
cmdop --debug login 2>&1 | tee auth-debug.log
 
# Check token manually
cat ~/.cmdop/auth.json | jq .