IP Whitelisting for API Keys
Bird
19 Aug 2015
1 min read
Key Takeaways
API keys are powerful credentials — if compromised, attackers can send email, steal data, or impersonate your brand.
Brute-forcing a 40-character hex key is essentially impossible; real threats come from exposure (MITM attacks, insecure code repos, leaked credentials).
Always use HTTPS and validate SSL certificates to prevent interception of your API keys.
IP whitelisting adds a critical layer of protection by restricting a key’s use to specific IPs or IP ranges.
Even if an attacker steals your API key, they cannot use it unless they are connecting from an approved IP.
CIDR support makes it easy to authorize entire networks without listing each server.
Avoid embedding API keys in code — use environment variables or secure secret-management solutions instead.
Create multiple narrow-scope API keys rather than a single “do-everything” key — each with limited permissions and its own whitelist.
For third-party integrations, create dedicated keys with restricted grants and restricted IPs.
Enable 2FA on your account since API keys can only be created via the UI.
Regularly review, rotate, and retire keys to maintain strong operational security.
Q&A Highlights
What is IP whitelisting?
It’s a security feature that restricts API key usage to specific IP addresses or IP ranges.
Why does SparkPost/Bird use API keys for authentication?
API keys are simple, widely adopted, and work cleanly with REST APIs and SMTP.
What happens if someone steals my API key?
They could send mail on your behalf, download recipient lists, modify templates, or send phishing/spam that damages your brand.
Can API keys be brute-forced?
Practically impossible. A 40-character hex string has ~1.46e48 combinations — brute-forcing would take longer than the age of the universe.
So how do attackers normally get API keys?
Man-in-the-middle attacks (if SSL isn’t verified), exposed keys in public GitHub repos, or logs accidentally leaking keys.
How does IP whitelisting help?
Even if an attacker steals your key, it won’t work unless they’re connecting from an approved IP.
Can I whitelist entire networks?
Yes, via CIDR notation — ideal for load-balanced servers, VPNs, or static office ranges.
Does whitelisting apply to both REST and SMTP?
Yes, the incoming request’s IP must match your whitelist.
How many IPs or ranges can I whitelist?
As many as you need — multiple individual IPs or blocks.
Should I use one API key for everything?
No. Create separate keys for different systems, teams, or vendors. This improves security and makes keys easier to rotate or revoke.
Where should I store API keys?
Use environment variables — never hard-code keys into source files or public repositories.
Any additional security best practices?
Always enable 2FA on your SparkPost/Bird account and create dedicated keys for third parties with minimal permissions and their own whitelists.
There are many ways to build authentication in an API-first product like SparkPost, and the one that we chose early on is the use of API keys. Injecting your API key as a raw Authorization header or via standard HTTP Basic Auth makes it very easy to use our APIs. API keys like this are a common standard for webservices, but how secure is this system?
The risks
When using any webservice, if an attacker gains your API key they can act on your behalf, and do things like (in our case):
send their email for free through your account
download your recipients list and feed them to spammers (if they are not spammers themselves)
edit your templates to inject phishing links
send spam or phishing on your behalf
Any of these outcomes could be very damaging to your reputation and to your business, and in the case of phishing potentially directly damage your end users. This is why it is extremely important to make sure no one can discover your API key.
The odds
IP whitelisting to the rescue
When you create an API key, you can now specify a list of IPs that are authorized to use this key. You can specify several IP, as well as IP blocks, using the CIDR notation, so you don’t have to list your servers individually. When the API key is used, for REST APIs or SMTP, we’ll match the connecting IP against this list to allow or deny access.
With this feature, even if your API key is found or stolen, only your servers will be able to use it. Given the risks and how easy it is to set it up, we highly recommend all our customers use this feature.
Last words
A few personal recommendations around security:
Do not keep your API keys in code. There is a lot of benefits in keeping them as environment variables, like Heroku does
You can create an unlimited amount of API keys, and it is best for security to split the responsibilities among several API keys, instead of only one swiss-knife key. This would also allow you to have different IP whitelists per key, for even better separation of concerns
If you work with third parties, do not share your API key but create a new one for them, with only the needed grants, and attached to their IPs
Since API keys can only be created via the UI, enabling 2-factor authentication on your SparkPost account is a must-have and takes only 2 minutes
