Authentication

Every request is authenticated with an API key sent as a bearer token.

curl "$ESIMIFY_API_URL/v1/balance" \
  -H "Authorization: Bearer sk_test_..."

A request without a key, with a malformed Authorization header, or with a key that is unknown, revoked or expired gets a 401 response with the code invalid_api_key. The message is the same in each case. Send the header once: a request with two Authorization headers is refused the same way.

Test and live keys

Key	Mode	Use it for
sk_test_...	Test	The sandbox. Nothing is bought and nothing is charged.
sk_live_...	Live	Real orders, charged to your partner balance.

Both kinds of key use the same base URL and the same paths. The key alone decides the mode. Objects made with one kind of key cannot be seen with the other.

Creating a key

1. Sign in to the Business portal at business.esimify.in and open Developers.
2. Go to the API keys tab and choose Test or Live.
3. Choose Create key and give the key a name that says which system uses it.
4. Optionally add the IP addresses the key may be used from.
5. Create the key and copy it.

The full key is shown once, when it is created. Store it straight away. eSIMify keeps only a fingerprint of it, so nobody can show it to you again. If you lose it, create a new one.

Afterwards the portal shows each key’s name, its first characters and last four characters, and when and from which address it was last used for an accepted request.

You can have up to 10 keys in each mode. Keys that are in their 24-hour roll-over period (see below) do not count towards the 10.

Live keys

A live key has two extra conditions:

• Your partner account must be approved for live orders. Until it is, the Developers page tells you why live keys are not available yet.
• You must enter your portal password to create one, and again to roll one.

A live key used on an account that is not approved for live orders gets 403 with the code live_mode_not_enabled.

Rolling a key

Rolling replaces a key without downtime.

1. In the portal, choose Roll key. For a live key you are asked for your portal password.
2. A new key is created and shown once. Copy it.
3. Put the new key into your system.
4. The old key keeps working for 24 hours, then it stops working on its own. You can also revoke it earlier.

Good to know:

• The new key starts with the same name and the same IP allowlist as the old one. From then on the two keys are separate: if you are moving servers, edit the new key’s allowlist.
• During the 24 hours both keys work. At most 20 keys can be usable at once in each mode, counting the ones that are being rolled.
• A key that has already been rolled cannot be rolled again while its replacement exists. Roll the replacement instead.
• Idempotency-Key values are shared by all keys of your account in the same mode. A request that timed out with the old key can be retried safely with the new one.
• Each key has its own rate limit.
• After the 24 hours a server that still sends the old key gets 401. Repeated 401 responses from one address block that address for a while, the new key included. See Keeping keys safe.

Roll keys on a schedule, and whenever someone who had access to a key leaves your team.

Revoking a key

Revoking takes effect immediately. Use it when a key may have leaked. Requests with a revoked key get 401.

Restricting by IP address

You can limit a key to the addresses of your own servers. A request from any other address is refused with 403 and the code ip_not_allowed, even with the right key.

• An entry is an IPv4 or IPv6 address, or a range in CIDR form such as 203.0.113.0/24.
• A key can have up to 20 entries.
• The allowlist works on test keys and live keys alike.
• A key with an empty allowlist can be used from any address.
• 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.

If your account is deactivated

Every request, with test keys and live keys alike, gets 403 with the code account_inactive. You cannot place orders, top up or read eSIMs, and no webhooks are sent. eSIMs your customers already have are not switched off by this. Email support@esimify.in or ask your eSIMify account manager.

Keeping keys safe

• Call the API from your server, never from a mobile app or a web page. A key inside an app can be read by anyone who downloads it.
• Keep keys in environment variables or a secrets manager, not in source code.
• Use a separate key for each system that calls the API, so you can revoke one without stopping the others.
• If a key may have leaked, revoke it immediately.

Repeated requests with a bad key from one address are blocked: after 60 failed attempts in 10 minutes, every request from that address gets 429 with a Retry-After header until the 10 minutes are over. This includes requests with a valid key, and everything behind one NAT address shares the count. Fix a bad key quickly.

Security has the full list.