Authentication

The DevTeam API supports two authentication methods: API keys for server-to-server communication and JWT tokens for user sessions.

API Keys

API keys are the recommended method for programmatic access. They are prefixed with dtk_ for identification.

Using API Keys

# Header (preferred)
curl -H "Authorization: Bearer dtk_live_abc123def456" \
  https://devteam.marsala.dev/api/tasks
 
# Query parameter (for webhooks and URLs)
curl "https://devteam.marsala.dev/api/tasks?api_key=dtk_live_abc123def456"

Key Types

Prefix	Type	Permissions
`dtk_live_`	Production	Full access based on role
`dtk_test_`	Test	Sandbox only, no production data
`dtk_worker_`	Worker	Task execution only

Creating API Keys

# Via CLI
devteam config create-key --name "CI Pipeline" --role operator
# Created key: dtk_live_abc123def456
# Store this key securely -- it will not be shown again.
 
# Via API
curl -X POST https://devteam.marsala.dev/api/auth/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI Pipeline", "role": "operator", "expiresIn": "90d"}'

Revoking Keys

devteam config revoke-key dtk_live_abc123

🚫

API keys grant persistent access. Rotate keys every 90 days and revoke immediately if compromised. Never store keys in source code or client-side applications.

JWT Authentication

JWT tokens are used for user sessions, typically from the dashboard or CLI.

Login

POST /api/auth/login
Content-Type: application/json
 
{
  "email": "admin@example.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "dtr_refresh_abc123",
    "expiresAt": "2026-02-21T10:00:00Z",
    "user": {
      "id": "usr_001",
      "email": "admin@example.com",
      "role": "admin",
      "name": "Admin User"
    }
  }
}

Using JWT Tokens

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://devteam.marsala.dev/api/tasks

Token Refresh

POST /api/auth/refresh
Content-Type: application/json
 
{
  "refreshToken": "dtr_refresh_abc123"
}

Token Expiry

Token Type	Default Expiry	Maximum
Access token	24 hours	7 days
Refresh token	30 days	90 days
API key	90 days	Never (manual revocation)

Role-Based Access Control (RBAC)

Roles

Role	Description	Permissions
`admin`	Full system access	All operations
`operator`	Task and plan management	Create/read/cancel tasks, plans, templates; manage HITL
`viewer`	Read-only access	Read tasks, plans, templates, status
`worker`	Worker node access	Execute tasks, update status, heartbeat

Permission Matrix

Resource	admin	operator	viewer	worker
Tasks: create	yes	yes	no	no
Tasks: read	yes	yes	yes	yes
Tasks: cancel	yes	yes	no	no
Tasks: execute	yes	no	no	yes
Plans: create	yes	yes	no	no
Plans: execute	yes	yes	no	no
Plans: read	yes	yes	yes	no
Templates: create	yes	yes	no	no
Templates: read	yes	yes	yes	no
Templates: deploy	yes	yes	no	no
HITL: approve/reject	yes	yes	no	no
HITL: read	yes	yes	yes	no
Workers: manage	yes	no	no	no
Auth: manage keys	yes	no	no	no
Auth: manage users	yes	no	no	no

User Management

# Create a user (admin only)
curl -X POST https://devteam.marsala.dev/api/auth/users \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "operator@example.com",
    "password": "secure-password",
    "name": "Jane Operator",
    "role": "operator"
  }'
 
# List users
curl https://devteam.marsala.dev/api/auth/users \
  -H "Authorization: Bearer $ADMIN_TOKEN"
 
# Update role
curl -X PATCH https://devteam.marsala.dev/api/auth/users/usr_002 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

Security Headers

All API responses include security headers:

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Strict-Transport-Security: max-age=31536000; includeSubDomains

Next Steps

Tasks API -- Task management endpoints
Errors -- Authentication error codes

Overview Tasks