The Nango proxy is an authenticated pass-through to external APIs. Send a request to Nango’s proxy with the target endpoint and connection details, and Nango resolves the provider’s base URL, injects the correct credentials, handles retries, and returns the external API’s response unmodified.
Use the proxy when you need to make one-off API calls on behalf of a user without writing sync or action functions.
All requests must include an Authorization: Bearer <secret-key> header. See Authentication for details.
How it works
Nango passes through the full response — status code, headers, and body — exactly as the external API returns it.
Endpoints
All five HTTP methods are supported:
| Method | Endpoint |
|---|
GET | GET /proxy/{endpoint} |
POST | POST /proxy/{endpoint} |
PUT | PUT /proxy/{endpoint} |
PATCH | PATCH /proxy/{endpoint} |
DELETE | DELETE /proxy/{endpoint} |
{endpoint} path is appended to the provider’s base URL. For example, /proxy/v3/contacts on a HubSpot connection becomes https://api.hubapi.com/crm/v3/contacts.
Bearer <secret-key> — your Nango secret key.
The ID of the connection to make the request on behalf of. Nango uses this to look up stored credentials.
The integration ID (unique key) identifying which provider’s base URL and auth scheme to use.
Override the provider’s default base URL. Use this when the target provider is not listed in Nango’s providers.yaml or when a connection requires a custom subdomain (common with Salesforce, ServiceNow, and similar enterprise APIs). Number of times Nango retries the request on failure (network errors or 5xx responses). Defaults to 0. Maximum is 10.
Comma-separated list of additional HTTP status codes that should trigger a retry. For example: 429,503.
Set to true to force decompression of the response body even if the external API does not set a Content-Encoding header.
Associates the proxy request with a specific activity log entry in the Nango dashboard. Used internally by Nango function runtimes.
Custom headers to forward to the external API. Strip the Nango-Proxy- prefix — for example, send Nango-Proxy-X-Custom-Header: value to pass X-Custom-Header: value to the external API.
Response
Nango passes the external API’s response through unchanged:
- Status code: exactly as returned by the external API.
- Headers: forwarded from the external API response.
- Body: the raw response body, with no transformation.
If the external API returns a 404, your application receives a 404. If it returns a 429, you receive a 429 (unless Retries is set, in which case Nango retries automatically).
ProxyConfiguration (Node SDK)
The Node SDK’s proxy methods accept a ProxyConfiguration object:
interface ProxyConfiguration {
// Required
endpoint: string; // Path appended to the provider's base URL
// Usually required (can be set on the Nango client at construction)
providerConfigKey?: string; // Integration ID
connectionId?: string; // Connection ID
// Request options
method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
data?: unknown; // Request body (POST, PUT, PATCH)
params?: string | Record<string, string | number | string[] | number[]>; // Query parameters
headers?: Record<string, string>; // Custom headers forwarded with Nango-Proxy- prefix
// Advanced options
baseUrlOverride?: string; // Override the provider's default base URL
retries?: number; // Retry count on failure (default: 0, max: 10)
retryOn?: number[] | null; // Additional status codes that trigger retries
decompress?: boolean; // Force response decompression
responseType?: 'arraybuffer' | 'blob' | 'document' | 'json' | 'text' | 'stream';
}
Examples
GET request — list GitHub issues
curl -X GET "https://api.nango.dev/proxy/repos/acme/backend/issues?state=open" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: github"
POST request — create a Salesforce record
curl -X POST "https://api.nango.dev/proxy/services/data/v59.0/sobjects/Contact" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: salesforce" \
-H "Content-Type: application/json" \
-d '{
"FirstName": "Ada",
"LastName": "Lovelace",
"Email": "[email protected]"
}'
curl -X PUT "https://api.nango.dev/proxy/crm/v3/contacts/12345" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: hubspot" \
-H "Content-Type: application/json" \
-d '{
"properties": {
"jobtitle": "Senior Engineer"
}
}'
PATCH request — update a Linear issue
curl -X PATCH "https://api.nango.dev/proxy/graphql" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: linear" \
-H "Content-Type: application/json" \
-d '{
"query": "mutation { issueUpdate(id: \"ISSUE_ID\", input: { stateId: \"STATE_ID\" }) { success } }"
}'
DELETE request — delete a Notion page
curl -X DELETE "https://api.nango.dev/proxy/v1/pages/page-id" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: notion"
Custom base URL (Salesforce instance)
Salesforce uses per-customer subdomain URLs. Override the base URL using Base-Url-Override (HTTP) or baseUrlOverride (SDK):
curl -X GET "https://api.nango.dev/proxy/services/data/v59.0/query?q=SELECT+Id+FROM+Account" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: salesforce" \
-H "Base-Url-Override: https://acme.my.salesforce.com"
With retries on rate limit
curl -X GET "https://api.nango.dev/proxy/2.0/repositories/acme/backend" \
-H "Authorization: Bearer $NANGO_SECRET_KEY" \
-H "Connection-Id: user-123" \
-H "Provider-Config-Key: bitbucket" \
-H "Retries: 3" \
-H "Retry-On: 429"
Node SDK methods
All five methods are wrappers around nango.proxy() that set the HTTP method automatically:
nango.get<T>(config: ProxyConfiguration): Promise<AxiosResponse<T>>
nango.post<T>(config: ProxyConfiguration): Promise<AxiosResponse<T>>
nango.put<T>(config: ProxyConfiguration): Promise<AxiosResponse<T>>
nango.patch<T>(config: ProxyConfiguration): Promise<AxiosResponse<T>>
nango.delete<T>(config: ProxyConfiguration): Promise<AxiosResponse<T>>
// Or call proxy() directly with an explicit method
nango.proxy<T>(config: ProxyConfiguration & { method: string }): Promise<AxiosResponse<T>>
AxiosResponse<T>, so response.data contains the parsed response body and response.status contains the HTTP status code.
Error handling
Connection not found
If the Connection-Id or Provider-Config-Key do not match a known connection, Nango returns 404:
{
"error": {
"code": "unknown_connection",
"message": "Connection not found for connection_id: user-123 and provider_config_key: github"
}
}
External API errors
Errors from the external API are passed through unchanged. If GitHub returns a 422 Unprocessable Entity, you receive the same 422 with GitHub’s original error body.
Credential injection failure
If Nango cannot retrieve or refresh credentials for the connection, it returns 401:
{
"error": {
"code": "invalid_credentials",
"message": "Could not refresh access token for connection user-123"
}
}
Use the Nango dashboard’s Logs tab to inspect full proxy request and response details, including headers, body, and timing — useful for debugging external API errors.
