or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-management.mdcore-types.mdidentity-operations.mdindex.mdrole-assumption.mdtoken-operations.mdutility-operations.md
tile.json

tessl/npm-aws-sdk--client-sts

AWS SDK for JavaScript STS Client for Node.js, Browser and React Native, providing temporary security credentials and role assumption capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@aws-sdk/client-sts@3.879.x

To install, run

npx @tessl/cli install tessl/npm-aws-sdk--client-sts@3.879.0

index.mddocs/

AWS SDK for JavaScript STS Client

The AWS SDK for JavaScript STS Client provides comprehensive APIs for the AWS Security Token Service (STS), enabling applications to request temporary, limited-privilege credentials for users. This package supports Node.js, browser, and React Native environments with first-class TypeScript support.

Package Information

  • Package Name: @aws-sdk/client-sts
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install @aws-sdk/client-sts
  • License: Apache-2.0
  • Minimum Node.js: 18.0.0

Core Imports

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

For CommonJS:

const { STSClient, GetCallerIdentityCommand } = require("@aws-sdk/client-sts");

For convenience wrapper:

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

Basic Usage

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

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

// Get current caller identity
const command = new GetCallerIdentityCommand({});
const response = await client.send(command);

console.log(`Account: ${response.Account}`);
console.log(`User ARN: ${response.Arn}`);

Architecture

The AWS STS Client is built on the modern AWS SDK v3 architecture with several key components:

  • Modular Design: Import only the specific commands you need to reduce bundle size
  • Command Pattern: Each STS operation is implemented as a separate command class
  • Middleware Pipeline: Comprehensive request/response processing with authentication, retry, and error handling
  • Multi-Platform: Unified API supporting Node.js, browsers, and React Native with platform-specific optimizations
  • TypeScript-First: Full type safety with generic type preservation and comprehensive interface definitions
  • Smithy Framework: Built on AWS's Smithy protocol framework for consistent service interactions

Capabilities

Client Management

Core client classes for initializing and managing STS service connections. Provides both command-based and convenience wrapper approaches.

import { Command } from "@smithy/smithy-client";
import type { Provider, AwsCredentialIdentityProvider, Logger, Endpoint } from "@smithy/types";

class STSClient {
  constructor(configuration?: STSClientConfig);
  send<InputType, OutputType>(command: Command<InputType, OutputType>): Promise<OutputType>;
  destroy(): void;
}

interface STSClientConfig {
  region?: string | Provider<string>;
  credentials?: AwsCredentialIdentityProvider;
  endpoint?: string | Provider<string> | Endpoint;
  maxAttempts?: number | Provider<number>;
  retryMode?: string | Provider<string>;
  useFipsEndpoint?: boolean | Provider<boolean>;
  useDualstackEndpoint?: boolean | Provider<boolean>;
  logger?: Logger;
  extensions?: RuntimeExtension[];
}

/** Generic provider type that can be a value or function returning value/promise */
type Provider<T> = T | (() => T) | (() => Promise<T>);

/** Interface for AWS credential providers */
interface AwsCredentialIdentityProvider extends Provider<AwsCredentialIdentity>;

/** AWS credential identity structure */
interface AwsCredentialIdentity {
  accessKeyId: string;
  secretAccessKey: string;
  sessionToken?: string;
}

/** Logger interface for debugging and monitoring */
interface Logger {
  trace?: (message: any, ...optionalParams: any[]) => void;
  debug?: (message: any, ...optionalParams: any[]) => void;
  info?: (message: any, ...optionalParams: any[]) => void;
  warn?: (message: any, ...optionalParams: any[]) => void;
  error?: (message: any, ...optionalParams: any[]) => void;
}

/** Endpoint configuration */
interface Endpoint {
  protocol?: string;
  hostname?: string;
  port?: number;
  path?: string;
  query?: Record<string, string>;
}

/** Runtime extension interface */
interface RuntimeExtension {
  configure(extensionConfiguration: STSExtensionConfiguration): void;
}

Client Management

Role Assumption

Operations for assuming IAM roles to obtain temporary credentials. Supports standard role assumption, cross-account access, SAML federation, and web identity federation.

class AssumeRoleCommand {
  constructor(input: AssumeRoleCommandInput);
}

interface AssumeRoleCommandInput {
  RoleArn: string;
  RoleSessionName: string;
  PolicyArns?: PolicyDescriptorType[];
  Policy?: string;
  DurationSeconds?: number;
  Tags?: Tag[];
  ExternalId?: string;
  SerialNumber?: string;
  TokenCode?: string;
}

Role Assumption

Identity Operations

Operations for retrieving information about the current caller identity and access keys. Essential for authentication verification and debugging credential issues.

class GetCallerIdentityCommand {
  constructor(input: GetCallerIdentityCommandInput);
}

interface GetCallerIdentityCommandInput {}

interface GetCallerIdentityResponse {
  UserId?: string;
  Account?: string;
  Arn?: string;
}

Identity Operations

Token Operations

Operations for obtaining session tokens and federation tokens for temporary access. Includes support for MFA requirements and federated user sessions.

class GetSessionTokenCommand {
  constructor(input: GetSessionTokenCommandInput);
}

interface GetSessionTokenCommandInput {
  DurationSeconds?: number;
  SerialNumber?: string;
  TokenCode?: string;
}

class GetFederationTokenCommand {
  constructor(input: GetFederationTokenCommandInput);
}

interface GetFederationTokenCommandInput {
  Name: string;
  Policy?: string;
  PolicyArns?: PolicyDescriptorType[];
  DurationSeconds?: number;
  Tags?: Tag[];
}

Token Operations

Utility Operations

Utility operations for decoding authorization messages and retrieving access key information. Helpful for debugging access denied errors and key management.

class DecodeAuthorizationMessageCommand {
  constructor(input: DecodeAuthorizationMessageCommandInput);
}

interface DecodeAuthorizationMessageCommandInput {
  EncodedMessage: string;
}

class GetAccessKeyInfoCommand {
  constructor(input: GetAccessKeyInfoCommandInput);
}

interface GetAccessKeyInfoCommandInput {
  AccessKeyId: string;
}

Utility Operations

Core Types

Essential data types and interfaces used throughout the STS API. Includes credentials, user identifiers, tags, and policy descriptors.

interface Credentials {
  AccessKeyId: string;
  SecretAccessKey: string;
  SessionToken: string;
  Expiration: Date;
}

interface AssumedRoleUser {
  AssumedRoleId: string;
  Arn: string;
}

interface Tag {
  Key: string;
  Value: string;
}

interface PolicyDescriptorType {
  arn?: string;
}

Core Types

Default Role Assumers

Factory functions for creating default role assumers used by credential providers. These functions provide standardized ways to assume roles and obtain temporary credentials for credential provider implementations.

function getDefaultRoleAssumer(
  stsOptions?: STSRoleAssumerOptions,
  stsPlugins?: Pluggable<ServiceInputTypes, ServiceOutputTypes>[]
): RoleAssumer;

function getDefaultRoleAssumerWithWebIdentity(
  stsOptions?: STSRoleAssumerOptions,
  stsPlugins?: Pluggable<ServiceInputTypes, ServiceOutputTypes>[]
): RoleAssumerWithWebIdentity;

type RoleAssumer = (
  sourceCreds: AwsCredentialIdentity,
  params: AssumeRoleCommandInput
) => Promise<AwsCredentialIdentity>;

type RoleAssumerWithWebIdentity = (
  params: AssumeRoleWithWebIdentityCommandInput
) => Promise<AwsCredentialIdentity>;

type STSRoleAssumerOptions = Pick<STSClientConfig, "logger" | "region" | "requestHandler"> & {
  credentialProviderLogger?: Logger;
  parentClientConfig?: CredentialProviderOptions["parentClientConfig"];
};

Role Assumption