Proxy actions

A proxy action allows you to make passthrough API calls to the SaaS provider’s API. Ampersand will attach the right authentication headers and also take care of token refreshes when necessary. To define a proxy action, add proxy as a key in your integration defined in amp.yaml:

specVersion: 1.0.0
integrations: 
  - name: proxy-intercom
    displayName: Proxy to Intercom
    provider: intercom
    proxy:
      enabled: true

​

Make API calls

All proxy actions expose an API with the base of https://proxy.withampersand.com. When making a passthrough call, simply replace the base URL with the Ampersand proxy URL. For example, instead of making a request to https://subdomain.my.salesforce.com/services/data/v56.0/sobjects/Account, making the same request to https://proxy.withampersand.com/services/data/v56.0/sobjects/Account.

Please refer to the Provider Guides for the base URL of each connector.

Keep the request body and HTTP verb the same, and add these additional headers so Ampersand knows how to deliver the API request:

• x-amp-proxy-version: this should always be 1
• x-amp-project-id: your Ampersand project ID. You can find it on your project’s General Settings page
• x-api-key: your Ampersand API key, if you don’t have one yet, create one in the Ampersand Dashboard’s API Keys page.

In order for Ampersand to know which SaaS instance to make the API call against, you’ll need to provide either:

• x-amp-installation-id: the installation ID, you’ll get this from the InstallIntegration component’s success callback functions.
• or both of the following:
  • x-amp-integration-name: the integration name that you wrote in the amp.yaml file
  • x-amp-group-ref: the ID for the user group that you used in the InstallIntegration React component’s groupRef property.

If all 3 headers (x-amp-installation-id, x-amp-integration-name & x-amp-group-ref) are provided, then the installation ID is used.

Here is an example API call:

curl --location --request PUT 'https://proxy.withampersand.com/services/data/v56.0/sobjects/Account' \
--header 'Content-Type: application/json' \ # Other content types are supported
--header 'x-amp-project-id: my-ampersand-project-id' \
--header 'x-api-key: my-api-key' \
--header 'x-amp-proxy-version: 1' \
--header 'x-amp-integration-name: my-salesforce-integration' \
--header 'x-amp-group-ref: company-id-from-my-app' \
--data '{
    # Same request body as if you are sending the request to Salesforce
}'

​

Use Ampersand to manage API rate limits

If you want Ampersand to help you with managing rate limits from provider APIs, set the X-Amp-Rate-Limiter-Mode request header to throttle. This means that if we receive a 429 HTTP status code from a provider, we will return information to you about when you should retry the request again. If you make another request before the suggested retry time, then we will not pass the request to the provider API. We do this because many providers penalize you for hitting too many 429 responses in a row.

In the API response, if you receive a 429 status code, you will find 2 additional headers:

• X-Amp-Retry-After: this includes a UTC timestamp of when Ampersand recommends you retry the request. For example: Thu, 06 Mar 2025 22:09:49 UTC.
• X-Amp-Retryable: this is a boolean that indicates whether the request is retryable. Most 429 request are retryable, however some API providers may “lock out” a particular token after too many unsuccessful requests, so that retrying isn’t possible.