AWS credentials

n8n offers two credential types for AWS:

• AWS (IAM): authenticate with an access key (Access Key ID and Secret Access Key).

• AWS (Assume Role): authenticate by assuming an IAM role through AWS STS. The credentials n8n uses for the AssumeRole call can be entered manually, or read automatically from the environment n8n runs in.

If you self-host n8n on AWS infrastructure (EKS, ECS, or EC2) and want to avoid storing static keys in n8n, see Using AWS system credentials.

AWS (IAM) credentials

You can use these credentials to authenticate the following nodes:

• AWS Bedrock Chat Model

• AWS Certificate Manager

• AWS Cognito

• AWS Comprehend

• AWS DynamoDB

• AWS Elastic Load Balancing

• AWS IAM

• AWS Lambda

• AWS Rekognition

• AWS S3

• AWS SES

• AWS SNS

• AWS SNS Trigger

• AWS SQS

• AWS Textract

• AWS Transcribe

• Embeddings AWS Bedrock

Supported authentication methods

• API access key

Related resources

Refer to AWS's Identity and Access Management documentation for more information about the service.

Using API access key

To configure this credential, you'll need an AWS account and:

• Your AWS Region

• The Access Key ID: Generated when you create an access key.

• The Secret Access Key: Generated when you create an access key.

To create an access key and set up the credential:

1. In your n8n credential, select your AWS Region.

2. Log in to the IAM console.

3. In the navigation bar on the upper right, select your user name and then select Security credentials.

4. In the Access keys section, select Create access key.

5. On the Access key best practices & alternatives page, choose your use case. If it doesn't prompt you to create an access key, select Other.

6. Select Next.

7. Set a description tag value for the access key to make it easier to identify, for example n8n integration.

8. Select Create access key.

9. Reveal the Access Key ID and Secret Access Key and enter them in n8n.

10. To use a Temporary security credential, turn that option on and add a Session token. Refer to the AWS Temporary security credential documentation for more information on working with temporary security credentials.

11. If you use Amazon Virtual Private Cloud (VPC) to host n8n, you can establish a connection between your VPC and some apps. Use Custom Endpoints to enter relevant custom endpoint(s) for this connection. This setup works with these apps:

    • Rekognition

    • Lambda

    • SNS

    • SES

    • SQS

    • S3

    • SSM

    • Bedrock

    Bedrock has two endpoint fields: Bedrock Endpoint, used to list available models, and Bedrock Runtime Endpoint, used for inference by the AWS Bedrock Chat Model and Embeddings AWS Bedrock nodes. Set both if you route Bedrock through a VPC interface endpoint (PrivateLink) without private DNS.

You can also generate access keys through the AWS CLI and AWS API. Refer to the AWS Managing Access Keys documentation for instructions on generating access keys using these methods.

AWS (Assume Role) credentials

You can use these credentials to authenticate the following nodes with enhanced security through IAM role assumption:

• AWS Bedrock Chat Model

• AWS Certificate Manager

• AWS Cognito

• AWS Comprehend

• AWS DynamoDB

• AWS Elastic Load Balancing

• AWS IAM

• AWS Lambda

• AWS Rekognition

• AWS S3

• AWS SES

• AWS SNS

• AWS SNS Trigger

• AWS SQS

• AWS Textract

• AWS Transcribe

• Embeddings AWS Bedrock

Supported authentication methods

• Role Assumption

Related resources

Refer to AWS's IAM Role documentation and STS AssumeRole documentation for more information about role assumption.

Understanding AWS Role Assumption

AWS Role Assumption allows you to securely access AWS resources by temporarily assuming an IAM role, rather than using long-lived access keys. This follows AWS security best practices and enables:

• Cross-account access: Access resources in different AWS accounts

• Enhanced security: Use temporary credentials that automatically expire

• Principle of least privilege: Grant only the permissions needed for specific tasks

• Audit trail: Better tracking of who accessed what resources

n8n uses the official AWS SDK to make the STS AssumeRole call. It requests fresh temporary credentials when it signs node requests, so you don't need to manage their expiry. This differs from the Temporary security credential option on the AWS (IAM) credential, where you enter a static session token that n8n can't renew: when that token expires, you must enter a new one.

Setting up AWS Assume Role credentials

To configure this credential, you'll need:

Required Parameters

• Region: The AWS region in which to call the STS service to assume the role. n8n calls the regional STS endpoint for this region. This includes the AWS China (cn-*) and AWS GovCloud (us-gov-*) partitions (available from n8n 2.29.0).

• Role ARN: The Amazon Resource Name (ARN) of the IAM role you want to assume. It has the format arn:aws:iam::123456789012:role/MyRole. This role must have a trust policy that allows your credentials to assume it.

• External ID: A unique identifier required by the role's trust policy to prevent the "confused deputy" problem. This should be a secret value that you generate and configure in both the role's trust policy and this credential. Treat this value as sensitive. Don't share it with other n8n users you don't trust.

• Role Session Name: A name for the assumed role session (used for auditing). Default values is n8n-session. This value appears in AWS CloudTrail logs so you can identify the session.

STS credentials (Choose one method)

You have two options for providing credentials to make the STS AssumeRole call:

Option 1: Use system credentials (recommended for server deployments)

Turn on Use System Credentials if the environment your n8n server runs in already has an AWS identity. n8n then discovers credentials for the AssumeRole call automatically, without storing static keys in n8n. n8n tries these sources in order and uses the first one that returns credentials:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN)

2. EKS IAM Roles for Service Accounts (IRSA)

3. EKS Pod Identity

4. ECS or Fargate task role

5. EC2 instance profile

This option requires your n8n administrator to enable system credentials access by setting the environment variable N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED to true. Refer to Using AWS system credentials for setup details and security considerations.

Option 2: Manual STS Credentials

If system credentials aren't available, provide these manually:

• STS Access Key ID: Access Key ID for an IAM user or role that has permission to assume the target role.

• STS Secret Access Key: Secret Access Key corresponding to the STS Access Key ID.

• STS Session Token (optional): Session token if using temporary credentials for the STS call.

Optional Parameters

• Custom Endpoints: If using Amazon VPC, you can specify custom endpoints for AWS services:

  • Rekognition Endpoint

  • Lambda Endpoint

  • SNS Endpoint

  • SES Endpoint

  • SQS Endpoint

  • S3 Endpoint

  • SSM Endpoint

  • Bedrock Endpoint (used to list available models)

  • Bedrock Runtime Endpoint (used for Bedrock inference, for example through a VPC interface endpoint (PrivateLink))

Setup Steps

1. Create the IAM Role in the target AWS account. This trust policy is for Option 2: Manual STS Credentials. If you use Option 1: Use system credentials, the Principal is the role n8n itself runs as. Refer to Trust policy for system credentials.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "AWS": "arn:aws:iam::SOURCE-ACCOUNT:root"
         },
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
             "sts:ExternalId": "your-unique-external-id"
           }
         }
       }
     ]
   }
   

2. Configure the credential in n8n.

   • Select your AWS Region

   • Enter the Role ARN of the role you created

   • Set a unique External ID (same as in the trust policy)

   • Choose your STS credentials method

   • Enter the Role Session Name (or use default)

3. Test the credential using the built-in test function to verify the role assumption works.

Security Best Practices

• Use unique External IDs for each credential to prevent unauthorized access.

• Rotate the STS credentials used for role assumption.

• Apply the principle of least privilege to both the assuming credentials and the target role.

• On shared instances, keep system credentials access disabled. Refer to Using AWS system credentials.

Using AWS system credentials (federated authentication)

This section is for administrators of self-hosted n8n instances.

System credentials access is for self-hosted n8n only. It's not available on n8n Cloud.

When n8n runs on AWS infrastructure, the infrastructure itself can provide an AWS identity. There are no access keys to create, store, or rotate. This is the standard way to authenticate workloads on EKS, ECS, and EC2, and security teams often require it ("zero static keys").

n8n reads these system credentials with the official AWS SDK credential providers, and uses them as the starting credentials for the AWS (Assume Role) credential when Use System Credentials is turned on. This works for all nodes that accept the AWS (Assume Role) credential, including the AWS Bedrock AI nodes.

System credentials are always the starting point for a role assumption, never the identity n8n calls AWS with directly. You must still enter a Role ARN, and that role must trust the identity n8n runs as.

If the role n8n already runs as has the permissions your workflows need, enter that same role's ARN and allow it to assume itself. Refer to Trust policy for system credentials.

Enabling access

Access to system credentials is disabled by default. To enable it, set this environment variable on every n8n instance (main and workers):

N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED=true

When enabled, any n8n user who can create an AWS (Assume Role) credential can use the server's own AWS identity as the starting point for role assumption. Only enable this on single-tenant, self-hosted instances where you trust everyone who can create credentials.

To limit what workflows can do with the server's identity, keep the server's own IAM permissions minimal. Ideally, grant just sts:AssumeRole on the specific roles workflows should use, each protected by an External ID.

Supported credential sources

n8n tries these sources in order and uses the first one that returns credentials:

Order	Source	How n8n detects it	Typical platform
1	Environment variables	AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (optionally AWS_SESSION_TOKEN)	Any
2	EKS IAM Roles for Service Accounts (IRSA)	AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE	Amazon EKS
3	EKS Pod Identity	AWS_CONTAINER_CREDENTIALS_FULL_URI	Amazon EKS
4	ECS or Fargate task role	AWS_CONTAINER_CREDENTIALS_RELATIVE_URI	Amazon ECS / Fargate
5	EC2 instance profile	EC2 instance metadata service (IMDSv2)	Amazon EC2

Things to keep in mind:

• AWS injects the detection variables for sources 2 to 4 automatically when you configure the platform feature. You don't set them yourself.

• If you set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY on the container, they take precedence over IRSA, Pod Identity, and instance roles. Remove them if you want the federated source to be used.

• n8n resolves system credentials when it needs them, so rotated or short-lived source credentials (for example, the IRSA token that Kubernetes rotates) are picked up automatically.

• Reading AWS CLI profiles from ~/.aws (AWS_PROFILE) is intentionally not supported.

Amazon EKS with IRSA

IAM Roles for Service Accounts associates an IAM role with the Kubernetes service account that runs n8n. Annotate the service account with the role ARN (eks.amazonaws.com/role-arn). EKS then injects AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE into the pod, and n8n exchanges the token with the regional STS endpoint.

Amazon EKS with Pod Identity

EKS Pod Identity is the newer alternative to IRSA. Install the Pod Identity Agent add-on and create a pod identity association between the n8n service account and an IAM role. No OIDC provider setup is needed.

Amazon ECS and Fargate

Assign a task role to the n8n task definition.

Amazon EC2

Attach an instance profile to the instance running n8n. n8n uses IMDSv2, so instances with IMDSv1 disabled work.

Trust policy for system credentials

The role you enter as Role ARN must trust the identity n8n runs as: the IRSA role, the Pod Identity role, the ECS task role, or the EC2 instance role. Use that role's ARN as the Principal, not the account root.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/n8n-service-account-role"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-unique-external-id"
        }
      }
    }
  ]
}

To find the ARN to use as the Principal, run aws sts get-caller-identity from inside the n8n container or instance.

If the role n8n runs as already has the permissions your workflows need, use that same role as the Role ARN and add its own ARN to its trust policy as shown above. AWS requires this even when a role assumes itself.

The role n8n runs as also needs sts:AssumeRole permission on the target role. Grant it on the specific roles workflows should use rather than on *.

AWS China and GovCloud

Available from n8n 2.29.0. On earlier versions, IRSA fails in the AWS China and GovCloud partitions because n8n called the global STS endpoint.

System credentials and role assumption work in all AWS partitions. n8n calls the regional STS endpoint for the credential's region: sts.{region}.amazonaws.com.cn in AWS China (cn-*) and sts.us-gov-{east,west}-1.amazonaws.com in AWS GovCloud (us-gov-*).

Proxy behavior

If your instance uses an HTTP(S) proxy (HTTPS_PROXY, HTTP_PROXY, NO_PROXY), n8n routes STS calls (the web identity exchange and AssumeRole) through it. Requests to link-local metadata services (EC2 IMDS, ECS and Pod Identity endpoints) always go directly, never through the proxy. These addresses are only reachable from the host itself.

Related environment variables

Variable	Default	Purpose
N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED	false	Allow the Use System Credentials option on AWS (Assume Role) credentials to read the server's AWS identity.
N8N_AWS_SYSTEM_CREDENTIALS_SDK_SOURCES	all	Transitional, available from n8n 2.29.0. Controls which system-credential sources resolve through the AWS SDK rather than n8n's legacy resolver. Accepts all, none, or a comma-separated subset of environment, roleForServiceAccount, podIdentity, containerMetadata, instanceMetadata. Only change this if AWS authentication broke after an upgrade. n8n removes this flag in a future release.
N8N_AWS_LEGACY_SIGNER	false	Transitional, available from n8n 2.30.0. Set to true to sign AWS requests with the legacy aws4 signer instead of AWS's Signature V4 implementation. Only use as a rollback if AWS requests fail after an upgrade. n8n removes this flag in a future release.

Troubleshooting

• "Access to AWS system credentials disabled, contact your administrator.": The Use System Credentials option is on, but N8N_AWS_SYSTEM_CREDENTIALS_ACCESS_ENABLED isn't set to true on the server.

• The wrong identity is used: Environment variables beat IRSA, which beats Pod Identity, ECS, and EC2. A stray AWS_ACCESS_KEY_ID in the container is the most common cause. Refer to Supported credential sources.

• Credential test fails on EKS: Verify the service account annotation (IRSA) or the pod identity association, and confirm the pod received the injected environment variables (kubectl exec <pod-name> -- env | grep AWS).

• AccessDenied when calling sts:AssumeRole: n8n found system credentials, but the target role rejected them. Check that the role's trust policy names the identity n8n runs as, and that the External ID matches the policy's condition. Refer to Trust policy for system credentials.