SETSimple Easy Transactions
SET DocsAPI reference and complianceUpdated 2026-11-10
Browse: Overview

Pinning a key to your servers

SET API, SET Merchant API and SET Direct Deposit API · Live since 2026-11-10

The problem

A leaked API key works from anywhere until you notice and revoke it. A vendor-risk review will also ask whether you can limit where your keys are accepted.

The answer: an IP allowlist on the key

Give the key the addresses your servers call from: up to 20 IPv4 or IPv6 addresses or CIDR ranges. A request with the key from any other address is refused with 403 ip_not_allowed, before anything runs.

KeySet the list
SET API or Merchant API keyWhen you issue it: POST /v1/api_keys {scopes, allowedCidrs}. Later: POST /v1/api_keys/{id}/allowed_cidrs {allowedCidrs}
Direct Deposit partner keyPOST /api/partner/keys/allowed_cidrs {allowedCidrs}, with the current partner key, or an admin on the partner dashboard
POST /v1/api_keys/key_…/allowed_cidrs
{ "allowedCidrs": ["203.0.113.0/24", "198.51.100.7", "2001:db8::/48"] }
  • The list you send replaces the one before. [] allows any address again.
  • Each change raises an event: api_key.allowed_cidrs_changed (SET API) or key.allowed_cidrs_changed (Direct Deposit). It shows in the audit log too.
  • Keys show their list as allowedCidrs.

You cannot shut yourself out

If you change the list of the key you are calling with, and the new list leaves out the address you are calling from, SET refuses it with 409 would_lock_out and changes nothing. Add your address, or change the list with another key (or from the partner dashboard).

Edge cases

  • Which address is checked. The address SET's network edge sees your request come from. Behind a NAT gateway or an egress proxy, that is the gateway's public address, not your server's private one.
  • A request that carries no address is refused.
  • A SET API key used on the Direct Deposit API is checked against its own list. It cannot change the partner key's list (403 partner_key_required).
  • The previous partner key, during a rotation overlap, cannot change the list (409 key_not_current). The list applies to both the current and the previous key.
  • Malformed entries are refused with 400 cidrs_invalid, naming the problem.