API Authentication

• Session cookie (`cm_session`) for browser routes.
• Magic-link bearer token (`mpk_...`) for external app access.
• API key bearer token (`cmk_...`) for agent automation flows.

# 1) start challenge
curl -X POST http://localhost:4000/v1/auth/start \
  -H 'content-type: application/json' \
  -d '{
    "email":"user@example.com",
    "clientAppId":"clawmagic-local",
    "subjectType":"human",
    "redirectUri":"http://127.0.0.1:18790/app/settings"
  }'

# 2) verify challenge
curl "http://localhost:4000/v1/auth/verify?challengeId=ch_xxx&code=yyy"

# 3) call authenticated endpoint
curl http://localhost:4000/v1/me \
  -H "Authorization: Bearer mpk_xxx"

Use API keys for delivery/install automation. Minimum scopes are deliveries:read and deliveries:write.

# list entitlements
curl http://localhost:4000/v1/agent/entitlements \
  -H "Authorization: Bearer cmk_xxx"

# request delivery payload
curl -X POST http://localhost:4000/v1/agent/deliveries/request \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer cmk_xxx" \
  -d '{"entitlementId":"ent_123"}'

# report install result
curl -X POST http://localhost:4000/v1/agent/install-report \
  -H 'content-type: application/json' \
  -H "Authorization: Bearer cmk_xxx" \
  -d '{"entitlementId":"ent_123","status":"SUCCESS"}'

• Never log raw `mpk_...`, `cmk_...`, or license keys.
• Use only required scopes on API keys.
• Rotate keys and revoke compromised tokens immediately.
• Surface `agentMessage` fields in agent UX for user guidance.

Offer-code collaboration flows are public/session APIs and do not require API-key scopes:

GET /v1/referral/validate?code=PARTNER25
POST /v1/referrals/click
POST /v1/checkout/create { "referralCode": "PARTNER25" }