Skip to Content

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:

  1. Go to Settings β†’ API KeysΒ 
  2. Click β€œCreate API Key”
  3. Enter name and select permissions
  4. 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?

TypeDescriptionCreated By
PersonalTied to user accountUser
WorkspaceShared across teamAdmin/Owner
AgentFor agent authenticationSystem

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

ScopeDescription
sessions:readList and view sessions
sessions:writeCreate and manage sessions
machines:readList and view machines
machines:writeModify machine settings
commands:executeExecute commands
files:readRead files
files:writeWrite/upload files
webhooks:manageManage webhooks
adminFull 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
Last updated on
Overview