What is a Proxy API? (2026 SaaS Architecture Guide)

If you are building B2B SaaS, your customers expect your product to talk to the tools they already use. What starts as a simple Jira ticket to "add a Salesforce integration" inevitably mutates into a massive, ongoing maintenance burden. You find yourself writing custom code to handle terrible vendor API documentation, aggressive rate limits, undocumented edge cases, and expiring OAuth tokens across dozens of platforms.

To solve this, modern engineering teams rely on a specific architectural pattern: the integration proxy layer.

A proxy API is a pass-through middleware layer that manages authentication, token lifecycles, pagination, rate limiting, and error normalization for outbound third-party API requests, while giving developers standard HTTP access to the provider's data.

That definition matters because the term "proxy" gets thrown around loosely. In the context of B2B SaaS integrations, a proxy API is not a reverse proxy sitting in front of your own services. It is an outbound proxy that your application calls to reach someone else's API. Instead of building custom infrastructure to handle the quirks of 50 different vendor APIs, your application makes a standard REST request to the proxy. The proxy handles the heavy lifting - injecting the correct credentials, managing the connection, normalizing errors - before forwarding the request to the destination.

Here is what a proxy API typically handles:

• Authentication lifecycle - Managing OAuth 2.0 flows, refreshing tokens before they expire, storing API keys securely, and injecting the correct Authorization header per request
• Pagination normalization - Translating cursor-based, page-based, offset-based, and link-header pagination into a consistent interface
• Rate limit detection - Intercepting HTTP 429 responses (or vendor-specific rate limit signals), extracting Retry-After values, and returning standardized headers to your client
• Request routing - Resolving the correct base URL, path template, and query parameters based on which vendor and resource you are targeting
• Error normalization - Converting each vendor's unique error shapes into a predictable structure your application can handle consistently

The proxy does not transform the data schema. If HubSpot returns properties.firstname and Salesforce returns FirstName, the proxy gives you exactly that. It is a transport layer, not a translation layer. That distinction is important - and it is where the proxy's relationship with unified APIs gets interesting (more on that below).

This guide breaks down exactly how a proxy API differs from an API gateway, what it costs to not have one, how the architecture works under the hood, and when you need it versus a unified API.

API Proxy vs. API Gateway: What's the Difference?

This is the most common source of confusion when engineering teams start researching proxy APIs. While both sit between a client and a server, they serve fundamentally different architectural purposes.

The short answer: an API gateway manages inbound traffic to your own internal services, while an integration proxy API manages your outbound traffic to external third-party vendors.

An API proxy is a simple intermediary between an application and the APIs that it uses to communicate. An API gateway is a centralized intermediary that accepts all incoming API requests, processes them in often complex ways and then forwards them to an application.

The overlap in terminology is real. API proxies and API gateways offer the same core functionality: Both can serve as an intermediary that isolates an application from API requests. But they do this with different levels of functionality.

An API Gateway (like Kong or Tyk) manages and protects your internal microservices. It sits at the edge of your infrastructure, handling inbound traffic from your users. Its primary jobs are routing requests to the correct internal service, enforcing security policies, and rate-limiting incoming traffic to protect your databases.

An Integration Proxy API manages your outbound requests to external third-party vendors. It acts as a mediator between your application and external services like Salesforce, HubSpot, or Jira. Its primary jobs are managing external OAuth credentials, standardizing third-party rate limits, and normalizing pagination.

API proxies are useful when you want to add a very specific (and simple) functionality to an existing API, while API gateways are useful when you want to manage and secure multiple APIs in a centralized manner.

But here is where the traditional definition falls short. In the B2B SaaS integration world, a proxy API is not "simple" at all. It has to handle dozens of authentication schemes, vendor-specific pagination quirks, GraphQL-to-REST translation, and rate limit normalization across 100+ providers. The complexity is just pointed in a different direction - outward, toward third-party vendors instead of inward toward your own services.

graph TD
  subgraph Your Infrastructure
    Client[Web/Mobile Client] --> Gateway[API Gateway<br>Inbound Protection]
    Gateway --> ServiceA[Core SaaS Application]
    ServiceA --> Proxy[Integration Proxy API<br>Outbound Management]
  end

  subgraph Third-Party SaaS Vendors
    Proxy --> SFDC[Salesforce API]
    Proxy --> Hubspot[HubSpot API]
    Proxy --> Jira[Jira API]
  end

Why B2B SaaS Needs a Proxy Layer for Third-Party Integrations

The math is bleak for teams building integrations from scratch.

A moderately complex API integration cost typically sits between $15,000 and $40,000. And that is just the initial build. Custom integrations can cost $50,000-$150,000 per year, including maintenance, vendor changes, and QA.

Multiply that by the number of integrations your customers actually need. 106 is the average number of SaaS apps per company in 2024. Even if you only support the top 20 tools your market requires, you are looking at a multi-million dollar annual commitment to keep those integrations alive.

The financial damage from poor integration infrastructure is not hypothetical. Poor integrations and lack of resources contribute to hundreds of lost orders each year, leading to annual revenue losses in the range of $250,000 to $500,000 for 57 percent of those surveyed. Cleo's follow-up research in 2023 found the problem only got worse: 99% of companies acknowledging they are losing money and missing out on business opportunities due to supply chain integration problems, more than a quarter of them (26%) admitted they are losing between $500,000 and $1,000,000 in revenue per year.

When you build a direct integration with a third-party API, you are not just writing a few HTTP GET requests. You are taking on a distributed systems problem. Every integration you build from scratch means your team is writing the same categories of code over and over:

1. OAuth token management - Implementing the authorization code flow, storing refresh tokens, handling token expiry, dealing with invalid_grant errors at 3 AM
2. Pagination plumbing - HubSpot uses cursor-based pagination with after. Salesforce uses nextRecordsUrl. BambooHR uses page numbers. Each requires different handling.
3. Rate limit logic - Salesforce returns rate limit info in response headers. HubSpot returns a Retry-After value. Some APIs just silently drop requests.
4. Error normalization - Every vendor returns errors differently. Some use HTTP status codes correctly. Some return 200 with an error buried in the response body.

Building integrations in-house drains your core product engineering team. A proxy layer eliminates this entire class of repetitive infrastructure work. By routing traffic through a proxy API, you offload the authentication, token management, pagination, and retry infrastructure. Your application simply says, "Get me the contacts for this connected account," and the proxy handles the rest.

How a Proxy API Works Under the Hood

A robust proxy API operates as a generic execution engine. It relies on declarative configuration rather than integration-specific code. Here is the lifecycle of a proxy API request - from the moment your application sends it to when you receive the response.

sequenceDiagram
    participant App as Your Application
    participant Proxy as Proxy API Layer
    participant Auth as Credential Store
    participant Vendor as Third-Party API

    App->>Proxy: GET /proxy/contacts/:id<br>(integrated_account_id=abc)
    Proxy->>Auth: Fetch credentials for account abc
    Auth-->>Proxy: OAuth token + context
    Proxy->>Proxy: Check token expiry,<br>refresh if needed
    Proxy->>Proxy: Resolve resource config,<br>build URL + headers
    Proxy->>Vendor: GET https://api.vendor.com/v3/contacts/123<br>Authorization: Bearer {token}
    Vendor-->>Proxy: 200 OK + JSON response
    Proxy->>Proxy: Parse response,<br>extract via response_path
    Proxy->>Proxy: Normalize rate limit headers
    Proxy-->>App: Standardized response envelope

Step 1: Resolve the connected account and credentials

When your application makes a request like GET /proxy/contacts/123?integrated_account_id=abc, the proxy first identifies the specific tenant making the request. It retrieves the integrated account - a stored record that ties a specific customer's connection to a specific vendor. This record holds the encrypted OAuth access token, refresh token, any API keys, and vendor-specific context data (like a Salesforce instance URL or a HubSpot portal ID).

If the connection uses OAuth 2.0, the proxy checks the time-to-live (TTL) on the access token. If the token is expired - or about to expire - the proxy intercepts the request, calls the vendor's token endpoint using the stored refresh token, updates the credentials, and then proceeds with the original request. Your application never sees expired token errors.

Step 2: Load the resource configuration and build the URL

The proxy does not have hardcoded logic for specific APIs. Instead, it looks up a resource configuration - a JSON blob that describes how to talk to the target API. This configuration dictates the base URL, the specific endpoint path (with placeholders for dynamic values like IDs), the authentication scheme required, default query parameters, the HTTP method, the body format, and pagination settings.

{
  "base_url": "https://api.hubspot.com",
  "path": "/crm/v3/objects/contacts/{{id}}",
  "auth_type": "bearer"
}

The proxy builds the final target URL by replacing placeholders in the configuration template with values from the incoming request, merging default headers with request-specific headers, and applying the correct authentication strategy (Bearer token, Basic auth, or custom header-based auth).

For APIs that require IP whitelisting, the request can be routed through a static IP proxy. This is more common than you would think with enterprise vendors.

Step 3: Execute the request and handle the response

The proxy attaches the correct credentials, formats the request body as JSON, form-urlencoded, multipart, or XML based on what the vendor expects, and forwards the HTTP request to the third-party provider.

Once the vendor responds, the proxy:

• Parses the response (JSON, XML, or binary) based on content type
• Extracts the relevant data using a configured response_path (e.g., data.results to pull items from a nested response envelope)
• Returns a consistent response envelope to your application

For list operations, the proxy also handles pagination automatically. Whether the vendor uses cursor-based, page-based, offset-based, or link-header pagination, your application always receives next_cursor and prev_cursor in the same format.

Step 4: Rate limit normalization

This is where handling API rate limits becomes critical. Every vendor handles rate limiting differently. Some return standard Retry-After headers in seconds. Others return Unix timestamps in custom headers like X-RateLimit-Reset. Some don't return headers at all and just drop the connection.

When a third-party API rate-limits a request, the proxy intercepts the response, detects the limit based on the vendor's specific configuration, and normalizes it. It returns a standard 429 status to your client along with a consistent Retry-After header, regardless of how the underlying vendor formatted it. Your code handles one retry pattern instead of dozens.

Converting GraphQL to REST via Proxy API

This is where proxy APIs get genuinely interesting from an architecture standpoint.

Some vendors - Linear, Shopify's Admin API, GitHub's v4 API - are GraphQL-only. They expose a single POST /graphql endpoint. For teams building integrations across dozens of services, switching between REST and GraphQL paradigms for every vendor creates real cognitive overhead.

A well-designed proxy API solves this by seamlessly translating GraphQL-backed integrations into standard RESTful CRUD resources using a configuration-driven approach. No code changes, no GraphQL client libraries needed on your side.

The Config-Driven Translation Bridge

The proxy layer translates between two distinct worlds:

• Client-facing: Familiar REST semantics (GET /proxy/issues, POST /proxy/issues)
• Provider-facing: A standard GraphQL POST with a query string and typed variables

Each method (list, get, create, update, delete) is backed by a config that defines:

• A GraphQL query or mutation template with placeholders like {{id}}, {{body.title:str:null}}, {{query.limit:int:null}}
• A response_path to extract the relevant data from the GraphQL response envelope (e.g., data.issues.nodes for a list, data.issueCreate.issue for a create)
• Pagination configuration mapped to cursor-based GraphQL patterns

From the client's perspective, the interface is identical to any other REST integration:

# List issues (proxy translates to GraphQL query under the hood)
GET /proxy/issues?integrated_account_id=abc&limit=20
 
# Create an issue (proxy translates to GraphQL mutation)
POST /proxy/issues?integrated_account_id=abc
{"title": "Fix auth bug", "team_id": "eng-123"}

The proxy receives these REST requests, loads the GraphQL template from configuration, substitutes placeholders with values from the request context, and sends a standard GraphQL POST to the vendor.

Extracting the Result

GraphQL responses are notoriously nested, always wrapped in a { "data": { ... } } envelope. The proxy strips this wrapper so your client receives just the relevant data array.

This is driven by the response_path configuration. For a list of issues, the configuration might specify data.issues.nodes. The proxy parses the GraphQL JSON response, traverses down to data.issues.nodes, extracts that specific array, and returns it directly to your application as a flat REST response.

From the perspective of your engineering team, Linear is just another REST API. The proxy handles the paradigm translation entirely in the background. This pattern means your team writes REST integrations for everything - whether the underlying vendor speaks REST, GraphQL, SOAP, or something else entirely.

Proxy API vs. Unified API: Which Do You Need?

This is not an either/or decision. If you are researching integration architectures, you will frequently see proxy APIs compared to unified APIs (similar to the embedded iPaaS vs. unified API debate). They are often framed as competing concepts, but in reality, they are complementary layers of the same API aggregator architecture.

A Proxy API normalizes the transport layer. It standardizes authentication, pagination, and rate limits, but it returns the exact data schema provided by the vendor. If you call the Salesforce API through a proxy, you get Salesforce's proprietary field names back.

A Unified API normalizes the data layer. It sits on top of the proxy layer. A unified API takes the raw vendor payload and transforms it into a standard, canonical schema. If you call a unified CRM API, you get a standardized Contact object back, regardless of whether the underlying data came from Salesforce, HubSpot, or Pipedrive.

The most practical architecture uses both. The unified API handles the 80% case - standard CRUD operations on common entities like contacts, employees, tickets, and invoices where you want one code path across all providers. The proxy API serves as the escape hatch for the other 20% - vendor-specific endpoints, custom objects, admin operations, and anything the unified model does not cover.

Why the Proxy is the Ultimate Escape Hatch

In well-designed platforms, the unified API is literally built on top of the proxy layer. The unified API adds a declarative mapping layer (transforming request queries, request bodies, and response fields using expressions) on either side of the same proxy transport that handles auth, pagination, and rate limits. A unified request like GET /unified/crm/contacts gets mapped into the vendor's native format, executed through the proxy, and the response gets mapped back into the common schema.

This layered architecture means nothing is lost. If the unified model does not expose a field you need, you drop down to the proxy and access it directly. If a vendor has a unique API endpoint with no unified equivalent, the proxy gives you full access without leaving the platform. One connected account, two access modes.

When a Proxy API is Not Enough

A proxy API solves the infrastructure problem, but it does not solve the data normalization problem.

If your product needs to display a unified list of contacts from Salesforce, HubSpot, and Pipedrive in the same table, a proxy API alone means you are still writing three different field-mapping functions. properties.firstname (HubSpot) vs. FirstName (Salesforce) vs. first_name (Pipedrive) - that mapping logic has to live somewhere.

Here are the scenarios where a proxy API alone falls short:

• Cross-provider reporting - Aggregating data from multiple vendors into a single view requires schema normalization
• Provider-agnostic features - Features like "sync all CRM contacts" that should work identically regardless of which CRM the customer uses
• AI agent tooling - LLM-based agents that need to understand a consistent data shape across vendors (though proxy APIs with good schema descriptions can work for agentic use cases where the LLM handles normalization)

For these use cases, you need the unified API layer on top. The proxy handles the transport; the unified layer handles the translation.

But there are absolutely valid scenarios where the proxy alone is exactly right:

• Single-vendor depth - You only integrate with one provider and need full access to its API
• Vendor-specific features - Custom objects, admin endpoints, proprietary workflows that no unified model would cover
• Debugging and testing - Seeing the exact raw response from a vendor to diagnose data issues
• Incremental migration - Starting with proxy access to ship fast, then layering unified models later as patterns emerge

The Zero-Storage Architecture Advantage

One of the most critical aspects of a modern proxy API is how it handles data security.

When you build point-to-point integrations, you often have to temporarily store third-party data in your own databases to process it, handle retries, or manage pagination state. This expands your compliance footprint significantly, creating headaches for SOC 2 and HIPAA audits.

A proper proxy API operates on a zero-storage architecture. The proxy acts strictly as a transit layer. It holds the encrypted OAuth credentials required to make the connection, but the actual data payloads - the CRM contacts, the HRIS employee records, the ticketing issues - pass through the proxy in memory.

The data is never cached, spooled, or persisted to a database within the proxy infrastructure. This ensures that your integration layer does not become a toxic asset of stored third-party PII.

Choosing the Right Architecture for Your Team

The decision tree is straightforward:

1. If you integrate with fewer than 3 providers and need deep access to their APIs → a proxy API gives you managed auth, pagination, and rate limits without boxing you into a schema
2. If you integrate with 5+ providers in the same category (CRM, HRIS, ticketing) and need a consistent interface → you need a unified API built on top of a proxy layer
3. If you integrate with 10+ providers across multiple categories → you need both, and you need the proxy as an escape hatch for the long tail of vendor-specific endpoints

The worst architectural decision is building 1:1 custom integrations without any proxy or abstraction layer. You end up with OAuth refresh logic duplicated across every integration, pagination code that subtly differs, and rate limit handling that works for HubSpot but silently fails for Salesforce. That technical debt compounds fast.

The second worst decision is adopting a unified API that offers no proxy or raw access mode. You will inevitably hit a wall when a customer needs a vendor-specific field or endpoint that the unified model does not cover, and you will have no way to access it without building a separate direct integration - defeating the entire purpose.

Look for platforms that give you both layers, sharing the same authentication infrastructure and credential store. One connected account, two access modes. That is the architecture that scales.