FAQ

Is there a sandbox?

No. There is no sandbox and no sandbox host. Keys beginning ez_test_ are rejected with 403 and code TEST_MODE_UNAVAILABLE before any handler runs, and only ez_live_ keys work.

The reason is that every v1 handler writes production records, provisions real Easy2257 users, and sends real email. A test key that reached those handlers would do all three against live data, which is precisely what a sandbox is supposed to prevent.

Rehearse against production with mailboxes you control, then DELETE the content you logged. Note that new partner accounts are issued a test key, so create a live key at partner.easy2257.com/api-keys before your first call.

How is idempotency handled?

With natural keys on the resource, not an Idempotency-Key header. Nothing reads that header.

Replays return the existing record with 200 instead of 201, and content-log replays add "duplicate": true.

POST /api/v1/collab-scenes and POST /api/v1/upload-sessions are not idempotent: each call creates a new scene or session, and the scene call also emails performers and charges fees. Dedupe those on your side.

What does a creator have to approve, and when?

Only when the email you provision already belongs to an Easy2257 user. Easy2257 will not hand an existing user's identity records to a platform on that platform's say-so, so it emails them and asks.

• The account stays unlinked and POST or DELETE on its content returns 409 (CONSENT_PENDING) until they approve.
• The account activates and solo_account.verified fires only after approval.
• If they decline, those routes return 409 with CONSENT_DECLINED, and they are never emailed about your platform again.
• The approval email is throttled to at most one per creator per day, so re-provisioning is safe but is not a way to nag.

Your provisioning response is identical in every one of these cases, so no code change is needed at step 1 and your integration cannot be used to probe whether one of your users already has an Easy2257 account.

Which statuses can I actually see?

Exactly four: pending_id_verification, subscribed_pending_id, active, suspended. Unlock uploads on active only.

Internal states are collapsed into pending_id_verification so that account existence and consent decisions are not observable. Do not code against any other value.

Note that the solo_account.verified webhook carries status: "verified", not "active". Match on event.type.

Where do webhooks get delivered?

To the endpoints you register at partner.easy2257.com/webhooks, and only those. The callbackUrl field on a solo account, collab scene, or upload session is stored for your reference and subscribes you to nothing.

Each endpoint has its own whsec_ signing secret, so you can rotate one integration without touching another. Deliveries carry X-EZ2257-Signature, X-EZ2257-Event, and X-EZ2257-Delivery, and are retried immediately, then at 1 minute, 5 minutes, 30 minutes, and 2 hours, with a 30-second timeout per attempt.

How do I rotate an API key without downtime?

Create the new key, deploy your client with it, confirm traffic has moved by watching lastUsedAt in the portal, then revoke the old one. A 24-hour overlap is conventional, and you can hold up to 10 active keys.

Keys are stored as SHA-256 hashes. The plaintext is shown once at creation and never again, so copy it into your secret store immediately. If you lose it, rotate.

When does Easy2257 return a 409?

Four cases, all of them state conflicts rather than replay errors:

One caveat on that last code, because it is the only one that is not a 409 everywhere: POST /v1/collab-scenes returns the same code as a 400, since there the identifier failing to resolve is a bad request rather than a state you can wait out. Match on code together with the route you called, not on code alone.

Replays never produce a 409. They return the original record with 200.

Are there rate limits?

Yes: 300 requests per 60 seconds, keyed by API key, applied to every /api/v1 request that presents an API key in the Authorization: Bearer header. It is a sliding window, and all v1 endpoints share one bucket per key, so it is a budget for each key's whole integration, not per endpoint — and other services on the same egress address do not draw it down. Requests without a key fall back to 60 per 60 seconds per client IP, and a per-address flood ceiling of 1200 per 60 seconds bounds keyed traffic during abuse. Other /api paths outside /api/v1 carry their own limits.

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (epoch milliseconds). Over the limit you get 429 with Retry-After in seconds and a body of { error, retryAfter, limit, remaining, reset }.

The normal integration shape stays well under this: one provisioning call per creator, one log call per upload, webhooks for the rest. Pace backfills and nightly sweeps, and honor Retry-After.

What is the versioning policy?

The version is in the path. There is no version header, and no response header signals a version, a deprecation, or an end-of-life date.

Additive changes ship without notice: new optional fields, new endpoints, new event types, new error codes. Ignore fields you do not recognize, and treat an unknown code as its HTTP status. Anything breaking ships as a new path version, and the changelog records what moved and what to do about it.

How long are records retained?

Easy2257 enforces a 7-year retention guard on 28 CFR Part 75 records: performer ID material, cross-reference index entries, and content logs. It holds regardless of account suspension or deletion.

Inside that window a takedown marks a depiction removed and stamps who removed it and why, rather than erasing it, which is what makes the trail survive the removal. Outside the window the record is deleted outright.

If your platform deletes user data under GDPR or CCPA, the Easy2257 records are exempt for the retention window. Tell the user that at deletion time.

What should I include in a support ticket?

• Your partner id, from the portal
• The approximate UTC timestamp of the request
• The request body with PII redacted, plus the response status and body
• For webhook issues: the event id (evt_...) and your endpoint URL

Email api@easy2257.com.