Authentication

Authorization: Bearer sk-ensemble-abc123...

ensemble conductor auth:token

API Token: sk-ensemble-abc123def456...
Expires: Never
Scopes: read:ensembles, execute:ensembles, write:ensembles

{
  "scopes": [
    "read:ensembles",
    "read:agents",
    "read:executions"
  ]
}

{
  "scopes": [
    "execute:ensembles",
    "execute:agents",
    "read:executions"
  ]
}

{
  "scopes": ["admin"]
}

curl -X POST https://your-worker.workers.dev/api/v1/tokens \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Token",
    "scopes": ["execute:ensembles", "read:executions"],
    "expiresIn": 2592000
  }'

{
  "token": "sk-ensemble-abc123...",
  "id": "tok_abc123",
  "name": "Production API Token",
  "scopes": ["execute:ensembles", "read:executions"],
  "expiresAt": 1708000000000,
  "createdAt": 1705408000000
}

curl https://your-worker.workers.dev/api/v1/tokens \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

{
  "tokens": [
    {
      "id": "tok_abc123",
      "name": "Production API Token",
      "scopes": [...],
      "lastUsed": 1705408000000,
      "createdAt": 1705315200000
    }
  ]
}

curl -X DELETE https://your-worker.workers.dev/api/v1/tokens/tok_abc123 \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

# .env.local
CONDUCTOR_API_TOKEN=sk-ensemble-abc123...

wrangler secret put CONDUCTOR_API_TOKEN
# Enter token when prompted

const token = process.env.CONDUCTOR_API_TOKEN;

const response = await fetch('https://your-worker.workers.dev/api/v1/execute/ensemble/my-workflow', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ input: {...} })
});

# .gitignore
.env
.env.local
.env.*.local

// Good: Only what's needed
{
  "scopes": ["execute:ensembles"]
}

// Bad: Over-permissioned
{
  "scopes": ["admin"]
}

# Create new token
ensemble conductor auth:token --name "Q1 2025"

# Update applications
# ...

# Revoke old token
ensemble conductor auth:revoke tok_old123

# 30-day expiration
ensemble conductor auth:token --expires-in 30d

# Check last used
ensemble conductor tokens:list

# View activity
ensemble conductor tokens:activity tok_abc123

GET /ensembles

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing authorization header"
  }
}

GET /ensembles
Authorization: Bearer invalid-token

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API token"
  }
}

POST /ensembles
Authorization: Bearer sk-ensemble-read-only...

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient scope: requires write:ensembles",
    "requiredScope": "write:ensembles",
    "providedScopes": ["read:ensembles"]
  }
}

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "API token expired",
    "expiredAt": 1705315200000
  }
}

// Future API
const oauth = new ConductorOAuth({
  clientId: 'your-client-id',
  redirectUri: 'https://yourapp.com/callback'
});

const authUrl = oauth.getAuthorizationUrl();
// Redirect user to authUrl

// In callback handler
const token = await oauth.exchangeCode(code);