> ## Documentation Index
> Fetch the complete documentation index at: https://nango.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS SigV4 Proxy

## Overview

<CardGroup cols={3}>
  <Card title="Pre-built tooling" icon="screwdriver-wrench" href="#pre-built-tooling" />

  <Card title="Pre-built integrations" icon="square-check" href="#pre-built-integrations" />

  <Card title="Access requirements" icon="triangle-exclamation" href="#access-requirements" />

  <Card title="Setup guide" icon="rocket" href="#setup-guide" />

  <Card title="Useful links" icon="circle-info" href="#useful-links" />

  <Card title="API gotchas" icon="biohazard" href="#api-gotchas" />
</CardGroup>

## Why use the AWS SigV4 integration?

* Reuse the Nango proxy to call AWS APIs (S3, CloudWatch, etc.) without storing customer credentials.
* Two modes for obtaining temporary credentials:
  * **Built-in AWS STS** — Nango calls AWS STS `AssumeRole` directly using your AWS credentials. No external service needed.
  * **Custom STS endpoint** — You host your own STS-style service that exchanges a customer IAM Role ARN + ExternalId for temporary AWS credentials.

## Access requirements

### Built-in AWS STS mode

| Pre-Requisites                   | Status         | Comment                                                                                                                    |
| -------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| AWS account with IAM permissions | ✅ Required     | Your AWS Access Key ID and Secret Access Key are stored securely in Nango's encrypted secrets column.                      |
| Customer AWS account             | ✅ Required     | Your customer creates an IAM role that trusts your AWS account with the ExternalId Nango generates (or that you pre-seed). |
| Custom STS endpoint              | ❌ Not required | Nango calls AWS STS directly.                                                                                              |

### Custom STS endpoint mode

| Pre-Requisites                   | Status     | Comment                                                                                               |
| -------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
| AWS account with IAM permissions | ✅ Required | Needed to host the STS endpoint and to register a trusted role in your own account.                   |
| Customer AWS account             | ✅ Required | Your customer creates an IAM role that trusts your STS role with the ExternalId.                      |
| Custom STS endpoint              | ✅ Required | Hosted by you (Docker container or similar). You expose the URL + auth in Nango integration settings. |

## Setup guide

Nango supports two STS modes. Choose the one that fits your setup.

### Option A: Built-in AWS STS (recommended)

Nango calls AWS STS `AssumeRole` directly — no external service to host.

<Steps>
  <Step title="Create an AWS SigV4 integration in Nango">
    1. From the Integrations page, add the **AWS SigV4 Proxy** template.
    2. In **Settings → General**, locate the AWS SigV4 configuration card.
    3. Select **Built-in AWS STS** as the STS mode.
    4. Enter the AWS service identifier you plan to call (for example `s3`).
    5. (Optional) Provide a default AWS region. End customers can override this during Connect.
    6. Enter your **AWS Access Key ID** and **AWS Secret Access Key**. These credentials are used to call `sts:AssumeRole` on behalf of your customers. They are stored in Nango’s encrypted secrets column and never exposed in the integration config.
    7. Click **Save**.
  </Step>

  <Step title="Onboard customers in your own application">
    Before opening Nango Connect, surface setup instructions (CloudFormation templates, manual IAM steps, etc.) in your own onboarding flow. Generate the ExternalId, show it to the customer so they can paste it into their IAM trust policy, and collect the resulting IAM Role ARN. Pre-seed the ExternalId into the Connect session so the value the customer sees in Connect matches what they configured.
  </Step>

  <Step title="Collect Role ARN & optional region during Connect">
    1. Create a Connect session, pre-filling `external_id` (and optionally `role_arn` / `region`) via `integrations_config_defaults` (see <a href="#pre-populating-credential-values">Pre-populating credential values</a>).
    2. The Connect UI shows the pre-seeded External ID read-only so the customer can confirm it matches their trust policy.
    3. When the end customer submits the form, Nango calls AWS STS `AssumeRole` with your credentials, tests the result via `GetCallerIdentity`, and stores a refreshable SigV4 credential.
  </Step>

  <Step title="Proxy AWS service calls">
    Call `POST /proxy` (or the SDK equivalents) exactly like other Nango connections. The proxy automatically refreshes temporary credentials through AWS STS and signs each request with SigV4 before forwarding it to AWS.
  </Step>
</Steps>

### Option B: Custom STS endpoint

You host your own STS-style service that exchanges credentials on behalf of customers.

<Steps>
  <Step title="Host or configure your STS endpoint">
    Deploy the SigV4 STS helper service (Docker or any HTTPS service) in your infrastructure. It must accept a JSON payload that includes `role_arn`, `external_id`, `region`, and `service`, assume the requested role, and return temporary AWS credentials (see <a href="#sts-endpoint-contract">STS endpoint contract</a>). Secure the endpoint using either an API key header or HTTP basic auth so Nango can authenticate the call.
  </Step>

  <Step title="Create an AWS SigV4 integration in Nango">
    1. From the Integrations page, add the **AWS SigV4 Proxy** template.
    2. In **Settings → General**, locate the AWS SigV4 configuration card.
    3. Select **Custom STS Endpoint** as the STS mode.
    4. Enter the AWS service identifier you plan to call (for example `s3`).
    5. (Optional) Provide a default AWS region. End customers can override this during Connect.
    6. Supply the STS endpoint URL and choose how Nango should authenticate (API key header or basic auth).
    7. Click **Save** to persist these settings.
  </Step>

  <Step title="Onboard customers in your own application">
    Before opening Nango Connect, surface setup instructions in your own onboarding flow. Generate the ExternalId, show it to the customer so they can paste it into their IAM trust policy, and collect the resulting IAM Role ARN. Pre-seed the ExternalId into the Connect session so the value the customer sees in Connect matches what they configured.
  </Step>

  <Step title="Collect Role ARN & optional region during Connect">
    1. Create a Connect session, pre-filling `external_id` (and optionally `role_arn` / `region`) via `integrations_config_defaults` (see <a href="#pre-populating-credential-values">Pre-populating credential values</a>).
    2. The Connect UI shows the pre-seeded External ID read-only so the customer can confirm it matches their trust policy.
    3. When the end customer submits the form, Nango calls your STS endpoint with the Role ARN + ExternalId, tests the credentials via `GetCallerIdentity`, and stores a refreshable SigV4 credential.
  </Step>

  <Step title="Proxy AWS service calls">
    Call `POST /proxy` (or the SDK equivalents) exactly like other Nango connections. The proxy automatically refreshes temporary credentials through your STS endpoint and signs each request with SigV4 before forwarding it to AWS.
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>

<Note>Contribute improvements to this guide by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/aws-sigv4.mdx)</Note>

## STS endpoint contract (custom mode only)

<Note>This section only applies when using **Custom STS Endpoint** mode. With **Built-in AWS STS** mode, Nango calls the AWS STS `AssumeRole` API directly and handles the request/response automatically.</Note>

The STS endpoint is customer-owned. Nango simply POSTs a JSON payload and expects temporary credentials in return.

```json title="Example request payload" theme={null}
{
    "role_arn": "arn:aws:iam::123456789012:role/NangoAccessRole",
    "external_id": "1bdff5dc-1b49-4f1c-9880-4402f8cad9cb",
    "region": "us-east-1",
    "service": "s3"
}
```

```json title="Example response payload" theme={null}
{
    "accessKeyId": "<TEMP ACCESS KEY>",
    "secretAccessKey": "<TEMP SECRET>",
    "sessionToken": "<SESSION TOKEN>",
    "expiresAt": "2025-01-31T17:28:00Z"
}
```

* You may wrap the response inside a `credentials` object; the helper accepts either shape.
* `expiresAt`/`expires_at`/`expiration` are interchangeable. Numeric values are treated as Unix seconds. If omitted, Nango assumes one hour.

## Pre-populating credential values

You can pre-seed `external_id`, `role_arn`, or `region` per Connect session via `integrations_config_defaults`. Pre-seeding the ExternalId is the recommended pattern: mint it in your onboarding flow, show it to the customer alongside their IAM trust-policy instructions, then pass the same value into Connect so the customer sees a matching read-only value.

```ts theme={null}
const { data } = await nango.createConnectSession({
    end_user: { id: 'user-123' },
    integrations_config_defaults: {
        'aws-sigv4': {
            connection_config: {
                external_id: '1bdff5dc-1b49-4f1c-9880-4402f8cad9cb',
                role_arn: 'arn:aws:iam::123456789012:role/NangoAccessRole',
                region: 'us-west-2'
            }
        }
    }
});
```

On reconnect flows the previously stored ExternalId is reused.

## Useful links

* [AWS Signature Version 4 signing process](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html)
* [AWS STS AssumeRole documentation](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
* [AWS IAM best practices for ExternalId](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)

<Note>Contribute useful links by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/aws-sigv4.mdx)</Note>