Docs

API key security

Protect Irisend API keys: the checksummed key format, automatic revocation of keys leaked on GitHub, a per-key IP allowlist, daily send caps and new-network alerts.

Key format and leak detection

New keys look like ir_<8 chars>_<30 chars>. The last six characters are a CRC-32 checksum of the rest, so secret scanners can tell a real Irisend key from a random string with almost no false positives. Older 36-character keys keep working; they have no checksum, so scanners cannot recognise them. Rotate them when convenient.

Irisend takes part in GitHub secret scanning. If a key is committed to a public repository, GitHub tells us, and we revoke it within moments, email the team's owners, and flag the account for review. A revoked key stops working immediately (requests fail with invalid_api_key) and disappears from the API list; create a replacement and remove the leaked one from the repository history.

To scan for Irisend keys yourself (for example in CI), match ir_[A-Za-z0-9]{8}_[A-Za-z0-9]{30}.

IP allowlist

Give a key a list of the addresses it may be used from, and Irisend refuses it from anywhere else. A stolen key is then useless to someone on another network.

  • Entries are single IPv4 or IPv6 addresses (203.0.113.7) or CIDR ranges (198.51.100.0/24, 2001:db8::/32). At most 20 per key. A range that matches every address (/0) is rejected: leave the list empty instead.
  • An empty list (the default) means the key works from anywhere.
  • Over REST a refused request is a 403 with invalid_access, and the message names the address Irisend saw. Over SMTP the login fails with 535. The check applies to every endpoint, not just sending.
  • The list is fail-closed: if Irisend cannot work out your address, a key with an allowlist is refused rather than let through. Irisend reads the address from the connection, taking the last X-Forwarded-For entry added by its own proxy, so a client cannot spoof it.
  • Servers behind a NAT gateway or a load balancer show the gateway's public address, not their own. Allow that one. A server with changing addresses (some serverless platforms) cannot use an allowlist; use a send cap instead.
  • Set it when you create the key, or change it later. In the dashboard, open API keys and choose Limits on a key. Changes apply to the next request.
curl -X POST https://api.irisend.com/api-keys \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production server",
    "permission": "sending_access",
    "ip_allowlist": ["203.0.113.7", "198.51.100.0/24"],
    "daily_send_cap": 5000
  }'
PATCH/api-keys/:idChange a key's limits
curl -X PATCH https://api.irisend.com/api-keys/3f9c2b1a-6e2d-4a3f-9c0b-1a2b3c4d5e6f \
  -H "Authorization: Bearer $IRISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ip_allowlist": ["203.0.113.7"], "daily_send_cap": null }'
ResponseJSON
{ "object": "api_key", "id": "3f9c2b1a-6e2d-4a3f-9c0b-1a2b3c4d5e6f" }

An allowlist does not replace keeping keys secret. For Connect on-behalf-of requests the check runs against the key you authenticate with, the parent's.

Daily send cap

daily_send_cap limits how many recipients (to + cc + bcc) one key may send per UTC day, on top of your team's quota. Past it, POST /emails answers 429 daily_quota_exceeded; other keys of the team are unaffected. Use a low cap on a key that lives somewhere you cannot lock down (a CI system, a customer-facing script). Send null to remove it.

New-network alerts

Irisend remembers which networks (country and provider) each key is used from. When a key appears on a network it has never been used from and its sending volume then jumps well above its own recent peak, Irisend emails your team's owners and shows the alert on the API keys page. A new location alone, or a busy hour alone, does not trigger it.

  • On accounts still in the Sandbox or New trust tier, the key is also limited to a small number of recipients a day until you confirm the activity.
  • If it was you, choose That was me on the alert: the limit is lifted. If it was not, revoke the key and create a new one.
  • The first network a key is ever used from is its baseline and never alerts.

See also API keys for the endpoints and Authentication.