Authentication
Separate agent capabilities from owner spending authority.
Keys and owner sessions
Public: GET /api/v1/capabilities and POST /api/v1/quotes. Other resources require authentication and belong to one workspace owner.
Authorization: Bearer YOUR_API_KEY
Keys have a 256-bit random secret: mr_test_ plus 64 hex characters for sandbox; mr_live_ plus 64 hex characters for managed provider operations. Store keys in a secret store, never URLs, public code, browser local storage, or logs. The full value is shown once; the database stores a SHA-256 hash. Owner accounts use Supabase email links and HttpOnly sessions. Open a sign-in link in the browser that requested it.
Scopes
| Scope | Operations |
|---|---|
| campaigns:read | Read campaigns, results, activity, assigned live assets and balance; reconcile balance top-ups |
| campaigns:write | Create campaigns; prepare/reconcile/pause live resources; upload creatives; request balance checkout links |
| events:write | Submit conversion observations |
Each agent should receive its own key. A sandbox key cannot mutate provider resources. A live key grants provider preparation and controls within its scope; it never grants spending approval. Revoke keys in the owner console.
Owner-only actions
Only the authenticated owner can create/revoke keys, accept advertiser consent, create campaign-specific checkout, or approve a campaign. The API refuses agent keys for those operations. Never request an owner's session token to bypass approval.
MarketingRouter operators separately assign Facebook identities, approved destination origins, and spending ceilings. A customer cannot list all of the operator's Facebook Pages or select another customer's creative. Whop credentials stay server-side.
Failure handling
401 means credentials are missing, invalid, or revoked. 403 means the principal lacks a scope or owner authority. Fix credentials or request the owner's action rather than repeatedly retrying. Cookie-authenticated writes enforce same-origin requests. Machine agents should use bearer authentication.
Live agents can request reusable balance top-ups, but the owner must authorize each hosted Whop payment. There is no saved-card charging scope or automatic refill. Email-free agent registration and social sign-in remain planned; currently the owner signs in and issues the initial scoped key.