Skip to main content

​
Overview

Pre-built tooling

Pre-built integrations

Access requirements

Setup guide

Useful links

API gotchas

​
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-RequisitesStatusComment
AWS account with IAM permissions✅ RequiredYour AWS Access Key ID and Secret Access Key are stored securely in Nango’s encrypted secrets column.
Customer AWS account✅ RequiredYour customer creates an IAM role that trusts your AWS account with the ExternalId Nango generates (or that you pre-seed).
Custom STS endpoint❌ Not requiredNango calls AWS STS directly.

​
Custom STS endpoint mode

Pre-RequisitesStatusComment
AWS account with IAM permissions✅ RequiredNeeded to host the STS endpoint and to register a trusted role in your own account.
Customer AWS account✅ RequiredYour customer creates an IAM role that trusts your STS role with the ExternalId.
Custom STS endpoint✅ RequiredHosted 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. Nango calls AWS STS AssumeRole directly — no external service to host.
1

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.
2

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.
3

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 Pre-populating credential values).
  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.
4

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.

​
Option B: Custom STS endpoint

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

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 STS endpoint contract). Secure the endpoint using either an API key header or HTTP basic auth so Nango can authenticate the call.
2

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.
3

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.
4

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 Pre-populating credential values).
  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.
5

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.
Need help getting started? Get help in the community.
Contribute improvements to this guide by editing this page

​
STS endpoint contract (custom mode only)

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.
The STS endpoint is customer-owned. Nango simply POSTs a JSON payload and expects temporary credentials in return.
Example request payload
{
    "role_arn": "arn:aws:iam::123456789012:role/NangoAccessRole",
    "external_id": "1bdff5dc-1b49-4f1c-9880-4402f8cad9cb",
    "region": "us-east-1",
    "service": "s3"
}
Example response payload
{
    "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. 
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.
Contribute useful links by editing this page