Security

An API key can spend your balance. Treat it like a password to your bank account.

Keep keys on your server

• Call the API from your server only. Never put a key in a mobile app, a web page, or anything else a customer can download.
• If your app needs eSIM data, have it call your own server, and have your server call eSIMify.
• Keep keys in environment variables or a secrets manager. Keep them out of source code, tickets, chat and screenshots.
• Do not write keys to your logs. If you log request headers, remove Authorization.
• Give each system its own key. Then you can revoke one without stopping the others, and the portal shows which system made which request.
• Use test keys in development and staging. Only production needs a live key.

A key is shown once, when it is created. eSIMify stores only a one-way fingerprint of it and cannot show it again.

Use the IP allowlist

Give every live key an allowlist with the addresses of your production servers. A stolen key is then no use from anywhere else.

• Entries are IPv4 or IPv6 addresses, or CIDR ranges. Up to 20 for each key.
• Requests from other addresses get 403 ip_not_allowed.
• The address checked is the one your request reaches the internet from. If your servers leave through a NAT gateway or a proxy, list that address.
• Requests refused by the allowlist appear on the Logs tab, so you can see where a stolen key was tried from.
• The allowlist works on test keys too.

Verify every webhook

Your webhook address is public. Without a check, anyone could tell your server that an order completed.

• Check the X-Esimify-Signature header on every request, with the raw body and a constant-time comparison. Webhooks has code for Node, PHP and Python.
• Refuse every request when your signing secret is missing from your configuration. An empty secret makes a signature anyone can compute.
• Reject requests whose timestamp is more than 5 minutes from your clock.
• Store each event id and ignore repeats.
• Serve the address over HTTPS with a valid certificate.
• Do not trust the body alone for anything that matters. When in doubt, fetch the order or the eSIM from the API.

Rotate secrets

Secret	How to rotate	What happens to the old one
API key	Roll it in the portal. A live key needs your portal password.	It keeps working for 24 hours, then it stops working on its own.
API key, leaked	Revoke it in the portal.	It stops working immediately.
Webhook signing secret	Rotate it in the portal.	It stops being used at once. Requests are signed with the new secret from then on.

Rotate on a schedule, and always when someone who had access leaves your team or a secret may have been exposed.

To rotate a webhook secret without dropping events, make your server accept either of two secrets for a short time. Rotate in the portal, add the new secret, then remove the old one. A delivery that fails in between is retried a minute later.

Limit who can do what

• Creating or rolling a live key needs the portal password of the person doing it. Five wrong passwords lock this for 15 minutes.
• Give portal access only to the people who need it.
• The Activity tab under Developers lists every change to keys and endpoints: who made it, when and from which address.

What eSIMify logs

So that you and our support team can trace a problem, each API request is recorded with:

• the request id, time, method and path
• the response status and how long the request took
• the mode, and the first characters of the key that was used
• the IP address the request came from
• the error code, if there was one
• the first 80 characters of the Idempotency-Key, if one was sent

You can see these records in the Business portal under Developers, on the Logs tab. They are kept for 30 days.

A request is recorded once its key has been recognised. A request sent with one of your keys that was revoked, or that has expired after a roll, is recorded too, with the status 401. This is how you find an old key that is still in use somewhere. A 401 for a missing key, or for a key that matches none of yours, is not in your log, because it cannot be tied to an account. The “last used” time of a key is the last request that was accepted.

The path is stored without its query string.

For webhooks, each delivery is recorded with the body that was sent, the status your server answered with and the first 500 characters of its answer. Do not put secrets in your webhook responses.

Changes to your keys and webhook endpoints are recorded against the portal user who made them, and shown on the Activity tab.

How long we keep things

What	Kept for
Request log	30 days
Events and webhook deliveries	30 days
Idempotency keys	At least 24 hours
Orders, eSIMs and top-ups	The life of your account

Because customer_ref and Idempotency-Key are stored and shown in logs, do not put personal data in either.

The QR code address

qr_code_url needs no API key. Anyone who has it can install the eSIM, and it cannot be revoked. Send it only to the customer the eSIM is for. See the QR code image.

If something goes wrong

1. Revoke the key or rotate the secret that may be exposed.
2. Check the Logs tab for requests you did not make. Note their request ids and addresses.
3. Check your recent orders with GET /v1/orders.
4. Email support@esimify.in with the request ids.

Report a vulnerability

If you find a security problem in the API, the portal or these docs, tell your eSIMify account manager. If you do not have one, email support@esimify.in and ask for the security contact. Give the steps to reproduce it. Do not include live API keys.