Why your API calls are getting a 401 when using embedded keys in the cloud

If your API calls are suddenly returning a 401 status code and you’re using embedded keys from a cloud server or VPN, don’t panic—you’re not alone, and you’re not broken. You're just bumping into a purposeful security measure designed to keep your address data (and ours) safe.

What are embedded keys and secret keys?

Smarty issues 2 types of API keys, each built for a different kind of job:

• Embedded keys are for client-side use. Think: web browsers and mobile apps. They’re designed to work when the end user's machine is directly making the call to Smarty's API.
• Secret keys are ONLY for server-side use. These are designed for backend code running on your infrastructure, including cloud servers.

You can manage and view both in your Smarty account’s API Keys page.

When do embedded keys break in the cloud?

If you're calling Smarty’s API with an embedded key and the call originates from a cloud provider like AWS, Azure, or Google Cloud—or even through some types of VPNs—you’re going to hit a wall. Specifically, you'll get this 401 error:

“Embedded key authentication is not allowed from public cloud providers.”

Why? It’s a security restriction. Cloud servers are often used by bad actors to spoof client-side traffic at scale. To prevent abuse and protect your usage limits (and your wallet), Smarty blocks embedded keys from working when the API call originates from a known public cloud IP address.

This often confuses developers because of how web applications behave.

Common use case: Where your site is in the cloud, but the API call is not

Let’s say you’re hosting your site on AWS. When a user visits your site, their browser downloads your JavaScript bundle. That code executes on their local machine, not the cloud server. When that JavaScript makes a call to Smarty, it’s coming from their browser, not AWS, and everything works fine. That’s the typical client-side scenario.

But what if you proxy those requests through your cloud server?

If your frontend code sends address data to your own server in the cloud, and that server then sends a request to Smarty, you’ve moved into server-side territory. In this case, you must switch to a secret key.

Using an embedded key here will trigger the dreaded 401, and no amount of retries or Stack Overflow scrolling will fix it.

Whitelisting cloud IPs: When (and when not) to do it

How to whitelist

1. Identify the public IP addresses your cloud servers use to make API calls.
2. Go to your Smarty API Keys page.
3. Click on the embedded key you’re using.
4. Use “Add Host” to whitelist each IP address individually.

Voilà! The calls will now succeed.

When not to whitelist

Whitelisting disables some of Smarty’s built-in security checks, including rate limiting by IP. That’s okay in controlled environments, but it can open you up to misuse if you’re not careful.

You should only whitelist IPs if:

• You trust the machines (and users) behind those IPs.
• You control those machines (e.g., a secure call center or corporate VPN).
• You have fewer than 100 public IPs you need to whitelist per embedded key.

If you’re managing a call center with 500 machines across dynamic IPs, setting up five embedded keys and mapping them to specific workstations quickly becomes a hot mess.

Consider a forward proxy instead

When you need to scale past 100 IPs—or just want better security and key management—implementing a forward proxy is the better move.

Here’s how that looks:

1. The end user submits address data via your front end.
2. Your front end forwards that request to your backend.
3. Your backend makes the API call to Smarty using a secret key.

This keeps your embedded keys safe, gives you better logging and control, and avoids the 401 errors entirely.

TL;DR

If you’re using embedded keys from a cloud server or VPN and getting 401 errors, here’s your checklist:

• Check if the request is coming from a cloud IP.
• If yes, either switch to using a secret key or whitelist the IP.
• Only whitelist IPs you control and trust.
• If you’re managing a large fleet of machines or users, use a forward proxy with secret keys instead.

Smarty’s goal is to protect your data, prevent API abuse, and keep your address requests flying at lightspeed. If you need help designing a more secure integration, reach out, and a real, unscripted human (who’s sitting next to the dev teams) will answer your questions. We’ve seen all the weird edge cases, and we’re happy to help you through yours.