API Reference

Authentication, conventions, and the full Easy2257 Partner API endpoint reference.

Easy2257 exposes a REST API over HTTPS. The endpoint reference is in the left nav — start with the conventions below.

Authentication

All requests require an API key as a Bearer token:

Authorization: Bearer ez_live_abc123...

Prefix	Environment
`ez_live_`	Production — charges real subscriptions
`ez_test_`	Sandbox — no real charges, ID verification auto-approves

Create keys in the Easy2257 partner dashboard. The secret is shown once at creation — copy it to your secret store immediately. To rotate without downtime: create a new key, deploy with it, verify traffic, then delete the old key (24-hour overlap recommended).

Idempotency

Include an Idempotency-Key header on every POST request:

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Use a UUIDv4. Easy2257 retains the key and response for 24 hours.

Scenario	Result
Same key, same params	Returns the original response
Same key, different params	`400 Bad Request`
Key in flight on another request	`409 Conflict`

For POST /v1/solo-accounts, pass externalUserId as the Idempotency-Key — it guarantees exactly one account per user.

Errors

Error responses use a flat envelope with the message in error and the HTTP status code as the source of truth:

{ "error": "externalUserId is required" }

Some endpoints additionally include a code field for programmatic handling:

{ "error": "performerEmail query parameter is required", "code": "missing_parameter" }

HTTP status	Meaning
400	Invalid request — missing or malformed parameter
401	Missing, invalid, expired, or revoked API key
403	Authenticated but not authorized for this resource (e.g. accessing another partner's account)
404	Resource not found (also returned for cross-partner access to avoid enumeration)
422	Request was understood but is in a state that doesn't allow the operation
500	Server error — retry with exponential backoff

Switch on HTTP status, not on the message text — error strings are not part of the API contract and may change.

Rate limits

60 requests per second per API key. When rate-limited:

Easy2257-Rate-Limited-Reason: request_rate
Retry-After: 1

Implement exponential backoff with jitter:

async function withRetry(fn, maxAttempts = 4) {
  for (let i = 0; i < maxAttempts; i++) {
    try { return await fn(); }
    catch (err) {
      if (err.status !== 429 || i === maxAttempts - 1) throw err;
      await new Promise(r => setTimeout(r, Math.min(1000 * 2 ** i + Math.random() * 100, 10000)));
    }
  }
}

Request IDs

Every response includes:

Request-Id: req_01HZABC123...

Include this in support tickets. Recent requests are also visible in the partner dashboard under Logs.

Versioning

Pin the API version you integrated against:

Easy2257-Version: 2026-04-25

If omitted, requests use the current default. Easy2257 commits to 90-day notice before any breaking change. Deprecated endpoints include Sunset and Deprecation response headers. Non-breaking changes (new optional fields, new endpoints, new event types, new error codes) are deployed without notice.

Metadata

Most resources accept a metadata object for storing platform-specific data:

{
  "metadata": {
    "platform_user_id": "usr_12345",
    "plan_tier": "creator_pro"
  }
}

Constraint	Limit
Keys per object	50
Key length	40 characters
Value length	500 characters
Value type	String only

Metadata is returned in all responses for that resource. It is not indexed or searchable.