# 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.

```http
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 Meta operations and paid creative generation. 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, creative jobs/previews, assigned live assets and balance; reconcile campaigns and balance top-ups |
| campaigns:write | Create/revise campaigns; prepare/pause live resources; generate/revise/publish creatives; upload assets; 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 advertising launch 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.

Guided setup provisions an isolated brand workspace and binds its approved Facebook Page and destination to the owner. Operators separately validate purchasing capacity and spending ceilings. A customer cannot access another workspace’s Pages or creatives. Advertising 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 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.

## Paid creative authorization

A live campaigns:write key can initiate paid creative generation and revisions when creative.enabled is true, even if advertiser setup is incomplete or live_spend_enabled is false. Issue this scope only to agents authorized to use the generation service. It does not debit advertising credit. campaigns:read can inspect existing jobs and refresh previews. Sandbox keys cannot generate, revise, publish, or read live creative jobs. Only owner approval can authorize campaign activation.