Security & billing

Safe architecture

Authenticated catalog calls and management cookies must never be exposed to public browser JavaScript. Your product UI talks to your backend; your backend holds the Bearer key (and, for portal operations, the management session).

Security checklist

Follow this list for every production deployment that touches the Developer Image API.

Common mistakes

• Do not create a single “god key” shared by every environment—blast radius is the entire product line.
• Do not spin parallel original downloads; one concurrent transfer is enforced per account.
• Do not retry 401/402/422 in a tight loop—fix config or billing first.
• Do not assume extra API keys increase the 30 req/min ceiling—they share one account budget.

Plan reminder

Developer Image API v1 has a free trial and one commercial plan:

• Free 1-month trial (instant key via POST /trial/signup: 2,000 requests, 2/minute, one trial per email); no per-image billing, credit balance, bundle pricing, or video access in v1.
• First-time subscribers get 20% off the first month ($40, then $50/month) automatically — see the pricing & upgrade page.
• All keys belonging to an account share the same rate limit and concurrent-download lease.
• Additional API keys can be created only after an active subscription (trials include one key).
• Base URL for catalog traffic: https://epochalstock.com/api/v1

Account & billing integration

The developer website (or your own admin backend) should proxy these management calls and keep the Epochal management session server-side. Do not expose management cookies or PayPal credentials to browser JavaScript.

Session & CSRF pattern

A typical server-side management client follows this order. Paths below are relative to the API base (https://epochalstock.com/api/v1) unless your deployment documents a separate portal host.

1. GET  /portal/csrf
   → Set-Cookie: management session
   → body/header includes CSRF token

2. POST /portal/register  (or /portal/login)
   Headers:
     Cookie: <session>
     X-CSRF-Token: <token>
     Content-Type: application/json
   Body (register): name, company, email, password (12+ chars)

3. POST /billing/subscription
   Headers: Cookie + X-CSRF-Token
   → returns PayPal approval URL for the $50/month plan

4. User approves in PayPal → webhook ACTIVE → account can create keys

5. POST /keys  { "name": "design-app-prod" }
   → secret shown once; store in secrets manager as EPOCHAL_API_KEY

6. Catalog traffic uses Bearer key only (no management cookie required)

# Illustrative only — cookie jar kept on your server, never in a browser SPA
BASE="https://epochalstock.com/api/v1"
COOKIE_JAR="$(mktemp)"

curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" "$BASE/portal/csrf"
# Parse CSRF token from response, then:

curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" -X POST "$BASE/portal/login" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"email":"you@example.com","password":"your-long-password"}'

curl -sS -c "$COOKIE_JAR" -b "$COOKIE_JAR" "$BASE/account" \
  -H "X-CSRF-Token: $CSRF"

rm -f "$COOKIE_JAR"

Subscription states & catalog access

Billing is webhook-driven. Approving PayPal is necessary but not sufficient until the platform records an ACTIVE subscription from a verified webhook event.

• Activation occurs only after PayPal reports ACTIVE (signed webhook).
• Webhook event IDs are idempotent—safe to process duplicates without double-applying state.
• POST /billing/cancel stops renewal; access continues through the already-paid period.
• Creating a second overlapping subscription may return 409 subscription_exists.
• Key limit is 20; excess create attempts return 409 key_limit_reached.

Commercial license

The commercial license at epochalstock.com/license applies to API usage and licensed images.

Monitoring, usage, and key rotation

Next steps