How Pega Cloud Calls Your Internal API: The NAT Gateway, Explained
How Pega Cloud Calls Your Internal API
This is the sequel to Connecting Your AWS VPC to Pega Cloud Privately. That article covered the organisation calling Pega. This one follows the same home loan the other way: Pega calling the organisation. The question: how does a Pega Cloud environment call an organisation's internally hosted API?
The use case
A customer applies for a home loan. The case runs in a Pega Cloud environment. Before it can decide, the case needs a credit score, so a Connect REST rule calls the credit score API.
That API isn't in Pega Cloud. The organisation hosts it on its own private servers, behind a firewall at the edge of its network.
Pega's side: the nodes are private
Pega's nodes sit in a private subnet. They have no public address and no direct route to the internet. A private subnet has no route to an internet gateway, so its resources need a NAT device to reach the internet.
Nothing on the internet can reach those nodes, and that is the point. But on their own, they can't reach the credit score API either.
The organisation's side: a firewall and an allow list
The credit score API runs on private servers in the organisation's network. A firewall at the edge lets a call in only if the caller's address is on its allow list. So the organisation has to know which address Pega's call will come from before it can allow it.
The NAT gateway answers that
A public NAT gateway is created in a public subnet and has an Elastic IP address. The private subnet's route table sends 0.0.0.0/0 to the NAT gateway. The public subnet's route table sends 0.0.0.0/0 to the internet gateway.
Think of it as a one-way door. Connections must always be initiated from within the VPC. The call goes out and the reply comes back. Nothing outside can start a connection in.
Pega Cloud's outbound connections originate from a pool of three static source IP addresses, shared by all system instances in Pega Cloud. Pega provisions these addresses and sends them to the client. Pega's own documentation calls them "NAT Gateway IPs (typically 3 IPs)" in one place and "static source IP addresses" in most others. The subnets inside Pega's account follow AWS's standard pattern, which is how the diagram labels them.
The whole call, hop by hop
- Pega node to NAT gateway. The home loan case runs on a Pega node in the private subnet. The credit score call goes to the NAT gateway in the public subnet.
- NAT gateway to internet gateway. The NAT gateway swaps the node's private address for its own. The call leaves through the internet gateway over HTTPS, with one of the static addresses as its source.
- Firewall. The organisation's firewall checks that address against its allow list.
- Credit score API. The address is on the list, so the call reaches the API.
- The reply. The score comes back the same way and the case moves on. The organisation never opened a way into Pega.
The organisation adds all three addresses to its allow list once.
Why the addresses need to be static
Pega runs more than one node for high availability. Nodes get added when load climbs, and replaced when one fails. Each new node gets a new private address. But every node calls out through the same NAT gateway, so the firewall still sees the same three addresses, and the organisation doesn't touch its firewall rules.
That holds while the egress pool stays as it is. The public documentation doesn't say what happens if the pool itself ever changes, so this article makes no claim about it. Confirm it with Pega.
A known address is not a proven caller
An address tells you where a call came from. It doesn't tell you who made it. Pega shares those three addresses across Pega Cloud, so the address alone doesn't prove the caller is your environment.
- OAuth 2.0 client credentials. A Connect REST rule can use an authentication profile for the OAuth 2.0 client credentials grant.
- Mutual TLS. Pega supports outbound mutual TLS. In Pega Cloud, it is set in the rules.
- No internet path at all. If the organisation wants none, Pega supports outbound AWS PrivateLink to an endpoint service the organisation builds.
Other ways to reach the organisation
| How Pega reaches the organisation | Source address the organisation sees | Notes |
|---|---|---|
| Public internet (this article) | Pega Cloud's static source addresses (three, shared across Pega Cloud) | Outbound is open by default. Allow-list all three. Authenticate the call |
| Direct Connect public VIF | The same static source addresses | Pega controls routing with BGP; addresses are unchanged |
| Outbound AWS PrivateLink into the organisation's VPC | The organisation's own load balancer addresses | The organisation builds an endpoint service (NLB, two or more matching AZs). Pega's ARN is allow-listed and the organisation accepts |
| Limit where Pega can call out | Not applicable | Pega Cloud Advanced Networking: licensed, Pega Cloud 3, deny by default, up to 100 endpoints |
Takeaway
Out, never in. Then prove who's calling. In practice: Pega's nodes stay private. The NAT gateway gives their calls static addresses. The organisation allow-lists them, and authenticates every call anyway.
More explainers at ssmone.cloud.