Authentication

Every request — including Sandbox — MUST carry a valid Bearer API key. There is no anonymous or public access to any endpoint. Keys are issued only from the partner portal: Developers → API Keys → New key.

Two key families:

• esm_sk_test_… — Sandbox (mock data, no charges). Requires its own key, issued from the Developers page with mode = Sandbox.
• esm_sk_live_… — Live (real provisioning, real billing).

Each key is 32 random characters after the prefix and is shown only once at creation. Lost keys cannot be recovered — revoke and create a new one.

Send it on every request:

curl https://portal.esimerge.com/api/public/v1/catalog \
  -H "Authorization: Bearer esm_sk_test_..."

Required. Every POST must include a unique Idempotency-Key header (8–128 characters: letters, digits, - or _; a UUID works well). Requests without it are rejected with 400 idempotency_key_required. Retried requests with the same key return the original response, and the key also fixes the upstream provider reference so a timed-out order can be recovered instead of provisioned twice. Keys are remembered for 24 hours.

Idempotency-Key: 8f0b1f9e-1f70-4a3e-9b3a-2c2bdcf7a1d2

Default: 60 requests / minute per API key. Bursts up to 120. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeding returns 429 rate_limited.

To protect partners and the platform we enforce, on every endpoint (Sandbox and Live alike):

• Mandatory authentication — any request without a valid, non-revoked key returns 401. Keys are stored hashed (SHA-256); the raw secret never leaves your machine after creation.
• Per-key rate limiting — 60 req/min with burst 120; offenders get 429.
• Idempotency on writes — duplicate retries cannot double-provision.
• Strict input validation on every field; malformed payloads return 400.
• Request logging — every call is logged with key id, partner id, request id, status, and latency for forensic review.
• One-click revocation from the Developers page if a key is leaked.

Every response carries X-Request-Id and a request_id in the body. Send it to support to speed up debugging.