Skip to main content

​
Package

@aws-sdk/client-sts

​
Installation

npm install @aws-sdk/client-sts

​
Creating the client

import { STSClient } from "@aws-sdk/client-sts";

const client = new STSClient({ region: "us-east-1" });
STS is a global service. Most operations work with any region, but you can use us-east-1 as a reliable default.

​
Commands

Returns the AWS account ID, IAM ARN, and user/role ID for the caller’s credentials. Requires no input parameters and works regardless of IAM permissions — any authenticated caller can invoke it.
import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";

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

const response = await client.send(new GetCallerIdentityCommand({}));

console.log({
  account: response.Account,    // "123456789012"
  arn: response.Arn,            // "arn:aws:iam::123456789012:user/alice"
  userId: response.UserId,      // "AIDACKCEVSQ6C2EXAMPLE"
});
This is commonly used in CI/CD pipelines to verify which credentials are active, and in Lambda handlers to log the execution context (see the working with Lambda page for a full example).
Returns short-lived credentials scoped to the assumed role. Use these when your code needs to act as a different IAM role, cross-account access, or service-to-service delegation.
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";

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

const response = await client.send(
  new AssumeRoleCommand({
    RoleArn: "arn:aws:iam::987654321098:role/CrossAccountRole",
    RoleSessionName: "my-app-session",
    DurationSeconds: 3600, // 1 hour (default: 3600, max: 43200)
    // Optional: scope-down policy
    // Policy: JSON.stringify({ Version: "2012-10-17", Statement: [...] }),
  })
);

const credentials = response.Credentials;
console.log({
  accessKeyId: credentials?.AccessKeyId,
  secretAccessKey: credentials?.SecretAccessKey,
  sessionToken: credentials?.SessionToken,
  expiration: credentials?.Expiration,
});
Exchange an OIDC token (e.g., from a Kubernetes service account, GitHub Actions, or Cognito) for temporary AWS credentials.
import {
  STSClient,
  AssumeRoleWithWebIdentityCommand,
} from "@aws-sdk/client-sts";

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

const response = await client.send(
  new AssumeRoleWithWebIdentityCommand({
    RoleArn: "arn:aws:iam::123456789012:role/WebIdentityRole",
    RoleSessionName: "web-session",
    WebIdentityToken: "<OIDC_TOKEN_FROM_IDP>",
    DurationSeconds: 3600,
  })
);

console.log(response.Credentials);
Returns temporary credentials for the current IAM user. Primarily used to generate credentials that satisfy MFA-required API calls.
import { STSClient, GetSessionTokenCommand } from "@aws-sdk/client-sts";

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

const response = await client.send(
  new GetSessionTokenCommand({
    DurationSeconds: 43200, // 12 hours
    // Required when MFA is enforced
    SerialNumber: "arn:aws:iam::123456789012:mfa/alice",
    TokenCode: "123456", // Current MFA code from authenticator app
  })
);

console.log(response.Credentials);

​
Using assumed-role credentials in another client

After calling AssumeRoleCommand, pass the returned credentials directly into another SDK client: 
import { STSClient, AssumeRoleCommand } from "@aws-sdk/client-sts";
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";

const stsClient = new STSClient({ region: "us-east-1" });

// Assume a role in another account
const assumeResponse = await stsClient.send(
  new AssumeRoleCommand({
    RoleArn: "arn:aws:iam::987654321098:role/S3ReadRole",
    RoleSessionName: "s3-read-session",
    DurationSeconds: 900,
  })
);

const { AccessKeyId, SecretAccessKey, SessionToken } =
  assumeResponse.Credentials!;

// Use the assumed credentials with S3
const s3Client = new S3Client({
  region: "us-west-2",
  credentials: {
    accessKeyId: AccessKeyId!,
    secretAccessKey: SecretAccessKey!,
    sessionToken: SessionToken,
  },
});

const objects = await s3Client.send(
  new ListObjectsV2Command({ Bucket: "cross-account-bucket" })
);
console.log(objects.Contents);

​
Credential chaining with fromTemporaryCredentials

Use the fromTemporaryCredentials helper from @aws-sdk/credential-providers to automatically refresh assumed-role credentials before they expire: 
import { S3Client } from "@aws-sdk/client-s3";
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";

const s3Client = new S3Client({
  region: "us-west-2",
  credentials: fromTemporaryCredentials({
    params: {
      RoleArn: "arn:aws:iam::987654321098:role/S3ReadRole",
      RoleSessionName: "auto-refresh-session",
      DurationSeconds: 3600,
    },
  }),
});

// Credentials are assumed on first use and refreshed automatically
fromTemporaryCredentials handles credential refresh transparently, so long-running processes do not need to manually call AssumeRoleCommand again.

Build docs developers (and LLMs) love

Get started for freeTalk to us