Introduction

If your AWS profile assumes a role, the JavaScript SDK can use it directly. The important part is that the shared profile must define how the role is assumed, and your SDK code must load credentials from that profile rather than hardcoding long-lived keys.

Define the Assume-Role Profile

In the shared AWS config, a role-based profile typically looks like this:

1[profile prod-admin]
2role_arn = arn:aws:iam::111122223333:role/AdminFromDev
3source_profile = default
4region = us-east-1

Here, default contains the base credentials, and prod-admin tells AWS tooling to assume the target role using those base credentials. This is the same pattern used by the AWS CLI, so keeping the profile correct is the first step.

Using the Profile With AWS SDK for JavaScript v3

For current JavaScript projects, the recommended SDK is v3. Load the shared profile with fromIni from @aws-sdk/credential-providers.

1import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
2import { fromIni } from "@aws-sdk/credential-providers";
3
4const client = new S3Client({
5  region: "us-east-1",
6  credentials: fromIni({ profile: "prod-admin" })
7});
8
9const result = await client.send(new ListBucketsCommand({}));
10console.log(result.Buckets);

fromIni reads the shared config, sees role_arn, uses the source profile, and performs the role assumption automatically. That means you do not call STS yourself for this basic case.

Using AWS_PROFILE Instead of Hardcoding

If you want the code to stay profile-agnostic, set the environment variable and let the default credential chain pick it up.

export AWS_PROFILE=prod-admin
node app.mjs

Then your client can often be created without an explicit credentials block:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });

This is often cleaner for local development because you can switch roles without touching application code.

What About the Older v2 SDK

You will still find examples using the old aws-sdk package. That package can also work with shared profiles, but new projects should generally prefer v3. If you are maintaining legacy code, the important idea is still the same: load credentials from the shared profile instead of embedding secrets.

The conceptual model does not change:

• the profile defines role_arn
• another profile or credential source provides the base credentials
• the SDK loads that profile and performs the assume-role step

Common Pitfalls

The most common mistake is putting the assume-role settings in the wrong profile or forgetting the base credential source. A role profile needs a source_profile or another valid credential source, otherwise the SDK has nothing to use for the first hop.

Another mistake is hardcoding the profile name in code that also runs in CI, Lambda, or containers. In those environments, the default provider chain and environment-specific credentials may be better than forcing a local profile.

Be careful with region settings. Role assumption and service calls are separate concerns, and a valid role profile does not automatically mean your service client is pointed at the intended region.

Finally, do not manually call STS unless you actually need custom assume-role behavior such as MFA prompts, external IDs, or session-name control. For standard shared-profile usage, the credential provider already knows what to do.

Summary

• Define role_arn and source_profile in the shared AWS config for the role-based profile.
• In JavaScript SDK v3, load that profile with fromIni.
• Use AWS_PROFILE when you want to switch profiles without changing code.
• Prefer the shared credential chain over hardcoded secrets.
• Reach for manual STS calls only when the shared-profile flow is not enough.