Skip to main content
The AWS SDK for JavaScript v3 requires valid AWS credentials to sign and authorize every request. This page explains the credentials structure, how the SDK resolves them, how caching works, and how to pass credentials to a client.

​
Credentials structure

An AWS credential object has four fields:
FieldTypeRequiredDescription
accessKeyIdstringYesThe AWS access key ID
secretAccessKeystringYesThe AWS secret access key
sessionTokenstringNoSession token for temporary credentials
expirationDateNoWhen the credentials expire
Any async function that returns this shape is a valid credential provider and can be passed directly to a client’s credentials option.

​
Credential resolution chain

When you initialize a Node.js client without explicit credentials, the SDK walks a default resolution chain and uses the first source that successfully returns credentials:
1

Explicit credentials or provider

Credentials passed directly in code to the client constructor take highest priority.
2

Environment variables

AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_SESSION_TOKEN.
3

SSO token cache

Credentials resolved from a cached AWS SSO/Identity Center token on disk.
4

Web identity token file

Credentials from an OIDC token file, read via AWS_WEB_IDENTITY_TOKEN_FILE and AWS_ROLE_ARN.
5

Shared INI files

~/.aws/credentials and ~/.aws/config, using the active profile.
6

Container and instance metadata

ECS task role metadata service, then EC2 instance metadata service (IMDSv1/v2).
Browsers have no default credential provider chain. You must supply credentials explicitly when running in a browser environment.

​
Credential caching

The SDK caches credentials per client instance. When the resolved credential object includes an expiration date, the SDK automatically calls the provider function again when fewer than 5 minutes remain before expiry. If no expiration is set, the provider is called only once per client lifetime. Because each client maintains its own cache, two clients configured with the same provider function will each fetch credentials independently. To share a single cached credential across multiple clients, create the provider once, call it yourself to warm the cache, or wrap it in your own memoization layer. 
import { fromIni } from "@aws-sdk/credential-providers";
import { S3Client } from "@aws-sdk/client-s3";
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";

// Each client caches independently — two fetches may occur.
const s3 = new S3Client({ credentials: fromIni() });
const dynamo = new DynamoDBClient({ credentials: fromIni() });

​
Passing credentials to a client

​
Static credentials object

Use a literal object only for local testing. Never commit real credentials to source control. 
import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  credentials: {
    accessKeyId: "AKIAIOSFODNN7EXAMPLE",
    secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  },
});

​
Credential provider function

Any async function matching the provider signature is accepted. The SDK will call it when credentials are needed or have expired. 
import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client({
  credentials: async () => {
    // fetch credentials from any source
    return {
      accessKeyId: "...",
      secretAccessKey: "...",
      sessionToken: "...",
      expiration: new Date(Date.now() + 3600 * 1000),
    };
  },
});

​
Built-in provider functions

The @aws-sdk/credential-providers package exports ready-made provider functions for every common credential source. 
import { S3Client } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";

const client = new S3Client({
  region: "us-east-1",
  credentials: fromIni({ profile: "my-profile" }),
});

​
Auth methods at a glance

Environment variables

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the shell. Ideal for CI/CD and containers.

Shared INI files

Read credentials from ~/.aws/credentials and ~/.aws/config using fromIni().

AWS SSO / Identity Center

Federated login via fromSSO(). Requires an active SSO session obtained with aws configure sso.

Assume role (STS)

Generate short-lived role credentials using fromTemporaryCredentials().

EC2 instance metadata

Automatically pick up the IAM role attached to an EC2 instance via fromInstanceMetadata().

ECS container metadata

Use the IAM role attached to an ECS task via fromContainerMetadata().

Web identity / OIDC

Exchange an OIDC token for temporary credentials using fromWebToken() or fromTokenFile().

Cognito Identity

Browser and mobile apps authenticate via Cognito using fromCognitoIdentity() or fromCognitoIdentityPool().

Default Node.js chain

Let the SDK try all sources automatically with fromNodeProviderChain().

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us