Start Checkout

Initiates a Stripe checkout session to create a new account, reactivate a cancelled one, or open the billing portal for an active one. This is the only self-serve onboarding path — POST /auth/register returns 410 Gone.

The endpoint has two modes selected by the presence of X-API-Key:

Request body

Anonymous mode (recommended for agents)

The typical agent signup flow. No pre-existing credentials are needed.

Request

curl -s -X POST \
  https://api.boringmarketing.com/auth/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "name": "Dev User",
    "tier": "builder"
  }'

Response (always this shape)

{
  "status": "email_sent",
  "session_id": "bmc_k7f3...",
  "poll_url": "https://api.boringmarketing.com/auth/checkout/bmc_k7f3.../status",
  "sent_at": "2026-04-08T18:42:11.123Z"
}

The server sends the Stripe URL to email. Tell the user to check their inbox, click the link, and complete payment. Then poll poll_url (see Checkout Status) until it returns completed.

How the user retrieves their API key

After payment completes, the poll endpoint returns {status: "completed", dashboard_url} — not an API key. Anonymous signups retrieve their key via the dashboard:

1. User opens dashboard_url.
2. User enters their email → receives a magic-link.
3. User clicks the link → lands in the dashboard.
4. User copies the key from Settings → API Access.

This indirection closes a security oracle that existed in an earlier version of the flow where the session_id alone was sufficient to claim a key.

Authenticated mode (fast path)

Use this mode when an agent already has an API key for the user and needs to upgrade a tier, reactivate a cancelled subscription, or open the billing portal.

The X-API-Key header must be present AND body.email must match the key-owner's email exactly.

Request

curl -s -X POST \
  https://api.boringmarketing.com/auth/checkout \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $BM_API_KEY" \
  -d '{
    "email": "you@example.com",
    "name": "You",
    "tier": "pro"
  }'

Response

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_live_...",
  "session_id": "bmc_m2p8...",
  "poll_url": "https://api.boringmarketing.com/auth/checkout/bmc_m2p8.../status",
  "flow": "new"
}

The flow field is a UX hint:

Auth failures

If X-API-Key is valid but body.email doesn't match the key-owner, the endpoint returns 401 with a generic error — deliberately indistinguishable from an invalid key. This prevents account enumeration via the checkout surface.

Rate limits

Anonymous mode is protected by a two-layer limiter:

A 429 response is identical whether the per-email or per-IP limit triggered — no oracle. If the user claims they didn't receive the first email, wait at least 60 seconds before retrying. A 4th POST within the hour will lock the address for the full window.

Authenticated mode is only bound by the per-IP limiter since the caller is already authenticated.

Error responses