Core client initialization, configuration options, and authentication setup for all IAM operations.
Low-level client class for sending commands with full configuration control.
/**
* IAM client for sending commands to AWS Identity and Access Management service
*/
class IAMClient {
constructor(config: IAMClientConfig);
send<InputType, OutputType>(command: Command<InputType, OutputType>): Promise<OutputType>;
destroy(): void;
}
interface IAMClientConfig {
/** AWS region for the client */
region?: string;
/** AWS credentials provider */
credentials?: AwsCredentialIdentityProvider;
/** Custom endpoint URL */
endpoint?: string;
/** Maximum number of retry attempts */
maxAttempts?: number;
/** Default mode for client behavior */
defaultsMode?: DefaultsMode;
/** HTTP handler for requests */
requestHandler?: HttpHandler;
/** Logger instance */
logger?: Logger;
/** User agent configuration */
userAgent?: UserAgent;
/** Signing configuration */
signer?: RequestSigner;
}
type DefaultsMode = "standard" | "in-region" | "cross-region" | "mobile" | "auto" | "legacy";Usage Example:
import { IAMClient, CreateUserCommand } from "@aws-sdk/client-iam";
// Basic client configuration
const client = new IAMClient({
region: "us-east-1",
maxAttempts: 3
});
// Advanced configuration with custom credentials
const advancedClient = new IAMClient({
region: "us-west-2",
credentials: {
accessKeyId: "your-access-key",
secretAccessKey: "your-secret-key"
},
maxAttempts: 5,
defaultsMode: "standard"
});High-level service class providing method-based interface for convenience.
/**
* High-level IAM service class with method-based interface
*/
class IAM {
constructor(config: IAMClientConfig);
// User operations
createUser(params: CreateUserRequest): Promise<CreateUserResponse>;
deleteUser(params: DeleteUserRequest): Promise<DeleteUserResponse>;
getUser(params?: GetUserRequest): Promise<GetUserResponse>;
listUsers(params?: ListUsersRequest): Promise<ListUsersResponse>;
updateUser(params: UpdateUserRequest): Promise<UpdateUserResponse>;
// Group operations
createGroup(params: CreateGroupRequest): Promise<CreateGroupResponse>;
deleteGroup(params: DeleteGroupRequest): Promise<DeleteGroupResponse>;
getGroup(params: GetGroupRequest): Promise<GetGroupResponse>;
listGroups(params?: ListGroupsRequest): Promise<ListGroupsResponse>;
// Role operations
createRole(params: CreateRoleRequest): Promise<CreateRoleResponse>;
deleteRole(params: DeleteRoleRequest): Promise<DeleteRoleResponse>;
getRole(params: GetRoleRequest): Promise<GetRoleResponse>;
listRoles(params?: ListRolesRequest): Promise<ListRolesResponse>;
// Policy operations
createPolicy(params: CreatePolicyRequest): Promise<CreatePolicyResponse>;
deletePolicy(params: DeletePolicyRequest): Promise<DeletePolicyResponse>;
getPolicy(params: GetPolicyRequest): Promise<GetPolicyResponse>;
listPolicies(params?: ListPoliciesRequest): Promise<ListPoliciesResponse>;
// Access key operations
createAccessKey(params?: CreateAccessKeyRequest): Promise<CreateAccessKeyResponse>;
deleteAccessKey(params: DeleteAccessKeyRequest): Promise<DeleteAccessKeyResponse>;
listAccessKeys(params?: ListAccessKeysRequest): Promise<ListAccessKeysResponse>;
updateAccessKey(params: UpdateAccessKeyRequest): Promise<UpdateAccessKeyResponse>;
}Usage Example:
import { IAM } from "@aws-sdk/client-iam";
const iam = new IAM({ region: "us-east-1" });
// Method-based interface - more convenient for simple operations
const user = await iam.createUser({
UserName: "test-user",
Path: "/developers/"
});
const groups = await iam.listGroups();
console.log(groups.Groups?.map(g => g.GroupName));Configuration for AWS authentication and credential management.
interface AwsCredentialIdentityProvider {
(): Promise<AwsCredentialIdentity>;
}
interface AwsCredentialIdentity {
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
expiration?: Date;
}
interface CredentialProviderOptions {
profile?: string;
roleArn?: string;
roleSessionName?: string;
externalId?: string;
mfaSerial?: string;
tokenCodeFn?: () => Promise<string>;
}Usage Example:
import { IAMClient } from "@aws-sdk/client-iam";
import { fromEnv, fromProfile, fromInstanceMetadata } from "@aws-sdk/credential-providers";
// Use environment variables
const clientWithEnvCreds = new IAMClient({
region: "us-east-1",
credentials: fromEnv()
});
// Use AWS profile
const clientWithProfile = new IAMClient({
region: "us-east-1",
credentials: fromProfile({ profile: "dev" })
});
// Use EC2 instance metadata
const clientWithInstanceCreds = new IAMClient({
region: "us-east-1",
credentials: fromInstanceMetadata()
});All operations use the Command pattern for consistent request/response handling.
/**
* Base command interface for all IAM operations
*/
interface Command<InputType, OutputType> {
input: InputType;
middlewareStack: MiddlewareStack<InputType, OutputType>;
resolveMiddleware(stack: MiddlewareStack<InputType, OutputType>): Handler<InputType, OutputType>;
}
interface Handler<InputType, OutputType> {
(args: HandlerExecutionContext & {
input: InputType;
}): Promise<HandlerOutput<OutputType>>;
}
interface HandlerExecutionContext {
logger?: Logger;
clientName?: string;
commandName?: string;
inputFilterSensitiveLog?: (input: any) => any;
outputFilterSensitiveLog?: (output: any) => any;
}
interface HandlerOutput<OutputType> {
output: OutputType;
response: HttpResponse;
}Usage Example:
import { IAMClient, ListUsersCommand } from "@aws-sdk/client-iam";
const client = new IAMClient({ region: "us-east-1" });
// Create command
const command = new ListUsersCommand({
PathPrefix: "/developers/",
MaxItems: 100
});
// Send command
try {
const response = await client.send(command);
console.log("Users:", response.Users);
} catch (error) {
console.error("Command failed:", error);
}Comprehensive error handling with typed exceptions.
/**
* Base exception class for IAM service errors
*/
class IAMServiceException extends Error {
name: string;
message: string;
$fault: "client" | "server";
$metadata: ResponseMetadata;
$service: "IAM";
$retryable?: {
throttling?: boolean;
};
}
interface ResponseMetadata {
httpStatusCode?: number;
requestId?: string;
extendedRequestId?: string;
cfId?: string;
attempts?: number;
totalRetryDelay?: number;
}
// Common exception types
class NoSuchEntityException extends IAMServiceException {
name: "NoSuchEntityException";
}
class EntityAlreadyExistsException extends IAMServiceException {
name: "EntityAlreadyExistsException";
}
class LimitExceededException extends IAMServiceException {
name: "LimitExceededException";
}
class InvalidInputException extends IAMServiceException {
name: "InvalidInputException";
}Usage Example:
import {
IAMClient,
CreateUserCommand,
EntityAlreadyExistsException,
InvalidInputException
} from "@aws-sdk/client-iam";
const client = new IAMClient({ region: "us-east-1" });
try {
await client.send(new CreateUserCommand({
UserName: "existing-user"
}));
} catch (error) {
if (error instanceof EntityAlreadyExistsException) {
console.log("User already exists");
} else if (error instanceof InvalidInputException) {
console.log("Invalid input provided");
} else {
console.error("Unexpected error:", error);
}
}Built-in pagination utilities for operations that return large result sets.
interface PaginationConfiguration {
client: IAMClient;
pageSize?: number;
startingToken?: string;
}
interface Paginator<T> {
[Symbol.asyncIterator](): AsyncIterator<T>;
}
// Example paginator function
function paginateListUsers(
config: PaginationConfiguration,
input: ListUsersCommandInput
): Paginator<ListUsersCommandOutput>;Usage Example:
import { IAMClient, paginateListUsers } from "@aws-sdk/client-iam";
const client = new IAMClient({ region: "us-east-1" });
// Paginate through all users
const paginator = paginateListUsers(
{ client, pageSize: 50 },
{ PathPrefix: "/developers/" }
);
for await (const page of paginator) {
console.log("Page of users:", page.Users?.map(u => u.UserName));
}Polling utilities for waiting on resource state changes.
interface WaiterConfiguration {
client: IAMClient;
maxWaitTime?: number;
minDelay?: number;
maxDelay?: number;
}
interface WaiterResult {
state: WaiterState;
reason?: string;
}
enum WaiterState {
SUCCESS = "SUCCESS",
FAILURE = "FAILURE",
RETRY = "RETRY",
TIMEOUT = "TIMEOUT"
}
// Available waiters
function waitForUserExists(
config: WaiterConfiguration,
input: GetUserCommandInput
): Promise<WaiterResult>;
function waitForRoleExists(
config: WaiterConfiguration,
input: GetRoleCommandInput
): Promise<WaiterResult>;
function waitForPolicyExists(
config: WaiterConfiguration,
input: GetPolicyCommandInput
): Promise<WaiterResult>;
function waitForInstanceProfileExists(
config: WaiterConfiguration,
input: GetInstanceProfileCommandInput
): Promise<WaiterResult>;Usage Example:
import { IAMClient, CreateUserCommand, waitForUserExists } from "@aws-sdk/client-iam";
const client = new IAMClient({ region: "us-east-1" });
// Create user
await client.send(new CreateUserCommand({
UserName: "new-user"
}));
// Wait for user to exist
const result = await waitForUserExists(
{
client,
maxWaitTime: 60 // seconds
},
{ UserName: "new-user" }
);
if (result.state === "SUCCESS") {
console.log("User is ready");
}