Authentication

TL;DR

CMDOP API supports two authentication methods: API keys (Bearer tokens) and OAuth 2.0. API keys use the format cmd_<workspace>_<random> and are passed via the Authorization: Bearer header. Three key types exist: Personal, Workspace, and Agent. Permissions are scope-based, including sessions:read, commands:execute, and admin.

How do I use API keys?

How do I include API keys in requests?

Include your API key in the Authorization header:


# Pass API key as Bearer token in the Authorization header
curl https://api.cmdop.com/v1/sessions \
  -H "Authorization: Bearer cmd_xxx"

How do I create an API key?

Via Dashboard:

Go to Settings → API Keys
Click “Create API Key”
Enter name and select permissions
Copy the key (shown only once)

Via CLI:


# Create a new API key with a descriptive name
cmdop auth create-key --name "my-script"

What is the API key format?


cmd_<workspace>_<random>

Example: cmd_acme_a1b2c3d4e5f6g7h8i9j0

What are the different key types?

Type	Description	Created By
Personal	Tied to user account	User
Workspace	Shared across team	Admin/Owner
Agent	For agent authentication	System

How do I use OAuth 2.0?

For user-facing applications.

What is the authorization URL?


https://auth.cmdop.com/oauth/authorize

What is the token URL?


https://auth.cmdop.com/oauth/token

What does the OAuth flow look like?


# 1. Redirect user to authorization
https://auth.cmdop.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=https://your-app.com/callback&
  response_type=code&
  scope=sessions:read+commands:execute
 
# 2. Exchange code for token
curl -X POST https://auth.cmdop.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=your_client_id" \
  -d "client_secret=your_client_secret" \
  -d "redirect_uri=https://your-app.com/callback"

What does the token response look like?


{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZn...",
  "scope": "sessions:read commands:execute"
}

What permissions and scopes are available?

Available Scopes

Scope	Description
`sessions:read`	List and view sessions
`sessions:write`	Create and manage sessions
`machines:read`	List and view machines
`machines:write`	Modify machine settings
`commands:execute`	Execute commands
`files:read`	Read files
`files:write`	Write/upload files
`webhooks:manage`	Manage webhooks
`admin`	Full administrative access

How do I check my current permissions?


# Verify your token and see assigned permissions
curl https://api.cmdop.com/v1/auth/me \
  -H "Authorization: Bearer cmd_xxx"

Response:


{
  "data": {
    "user_id": "usr_abc123",
    "email": "[email protected]",
    "workspace_id": "ws_xyz789",
    "permissions": [
      "sessions:read",
      "sessions:write",
      "commands:execute"
    ]
  }
}

What error responses can authentication return?

Invalid Token (401)


{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"
  }
}

Insufficient Permissions (403)


{
  "error": {
    "code": "forbidden",
    "message": "Missing required permission: commands:execute",
    "details": {
      "required": "commands:execute",
      "available": ["sessions:read", "files:read"]
    }
  }
}

Token Expired (401)


{
  "error": {
    "code": "token_expired",
    "message": "Access token has expired"
  }
}

How do I manage tokens and keys?

How do I list my keys?


# List all API keys associated with your account
curl https://api.cmdop.com/v1/auth/keys \
  -H "Authorization: Bearer cmd_xxx"

How do I revoke a key?


# Permanently revoke a specific API key by its ID
curl -X DELETE https://api.cmdop.com/v1/auth/keys/key_abc123 \
  -H "Authorization: Bearer cmd_xxx"

How do I rotate a key?


# Rotate key: invalidates old key and returns a new one
curl -X POST https://api.cmdop.com/v1/auth/keys/key_abc123/rotate \
  -H "Authorization: Bearer cmd_xxx"

What are the security best practices?

1. Use Environment Variables


# Never hardcode keys
export CMDOP_API_KEY=cmd_xxx


import os
# Read the API key from environment variable at runtime
api_key = os.environ["CMDOP_API_KEY"]

2. Minimum Permissions


# Create key with only needed permissions
cmdop auth create-key --name "read-only" --permissions sessions:read,files:read

3. Rotate Regularly


# Rotate keys periodically
cmdop auth rotate-key cmd_xxx

4. Use Separate Keys


Personal laptop:    cmd_acme_alice_xxx
CI/CD pipeline:     cmd_acme_cicd_yyy
Production server:  cmd_acme_prod_zzz

5. Monitor Usage


# View key usage
cmdop auth key-usage cmd_xxx

What should I read next?

Sessions API — Session management
Commands API — Execute commands