Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@aws-sdk/client-cognito-identity-provider

aws4.9mApache-2.03.760.0TypeScript support: included

AWS SDK for JavaScript Cognito Identity Provider Client for Node.js, Browser and React Native

readme

@aws-sdk/client-cognito-identity-provider

Description

AWS SDK for JavaScript CognitoIdentityProvider Client for Node.js, Browser and React Native.

With the Amazon Cognito user pools API, you can configure user pools and authenticate users. To authenticate users from third-party identity providers (IdPs) in this API, you can link IdP users to native user profiles. Learn more about the authentication and authorization of federated users at Adding user pool sign-in through a third party and in the User pool federation endpoints and managed login reference.

This API reference provides detailed information about API operations and object types in Amazon Cognito.

Along with resource management operations, the Amazon Cognito user pools API includes classes of operations and authorization models for client-side and server-side authentication of users. You can interact with operations in the Amazon Cognito user pools API as any of the following subjects.

  1. An administrator who wants to configure user pools, app clients, users, groups, or other user pool functions.

  2. A server-side app, like a web application, that wants to use its Amazon Web Services privileges to manage, authenticate, or authorize a user.

  3. A client-side app, like a mobile app, that wants to make unauthenticated requests to manage, authenticate, or authorize a user.

For more information, see Understanding API, OIDC, and managed login pages authentication in the Amazon Cognito Developer Guide.

With your Amazon Web Services SDK, you can build the logic to support operational flows in every use case for this API. You can also make direct REST API requests to Amazon Cognito user pools service endpoints. The following links can get you started with the CognitoIdentityProvider client in supported Amazon Web Services SDKs.

To get started with an Amazon Web Services SDK, see Tools to Build on Amazon Web Services. For example actions and scenarios, see Code examples for Amazon Cognito Identity Provider using Amazon Web Services SDKs.

Installing

To install this package, simply type add or install @aws-sdk/client-cognito-identity-provider using your favorite package manager:

  • npm install @aws-sdk/client-cognito-identity-provider
  • yarn add @aws-sdk/client-cognito-identity-provider
  • pnpm add @aws-sdk/client-cognito-identity-provider

Getting Started

Import

The AWS SDK is modulized by clients and commands. To send a request, you only need to import the CognitoIdentityProviderClient and the commands you need, for example ListDevicesCommand:

// ES5 example
const { CognitoIdentityProviderClient, ListDevicesCommand } = require("@aws-sdk/client-cognito-identity-provider");
// ES6+ example
import { CognitoIdentityProviderClient, ListDevicesCommand } from "@aws-sdk/client-cognito-identity-provider";

Usage

To send a request, you:

  • Initiate client with configuration (e.g. credentials, region).
  • Initiate command with input parameters.
  • Call send operation on client with command object as input.
  • If you are using a custom http handler, you may call destroy() to close open connections.
// a client can be shared by different commands.
const client = new CognitoIdentityProviderClient({ region: "REGION" });

const params = {
  /** input parameters */
};
const command = new ListDevicesCommand(params);

Async/await

We recommend using await operator to wait for the promise returned by send operation as follows:

// async/await.
try {
  const data = await client.send(command);
  // process data.
} catch (error) {
  // error handling.
} finally {
  // finally.
}

Async-await is clean, concise, intuitive, easy to debug and has better error handling as compared to using Promise chains or callbacks.

Promises

You can also use Promise chaining to execute send operation.

client.send(command).then(
  (data) => {
    // process data.
  },
  (error) => {
    // error handling.
  }
);

Promises can also be called using .catch() and .finally() as follows:

client
  .send(command)
  .then((data) => {
    // process data.
  })
  .catch((error) => {
    // error handling.
  })
  .finally(() => {
    // finally.
  });

Callbacks

We do not recommend using callbacks because of callback hell, but they are supported by the send operation.

// callbacks.
client.send(command, (err, data) => {
  // process err and data.
});

v2 compatible style

The client can also send requests using v2 compatible style. However, it results in a bigger bundle size and may be dropped in next major version. More details in the blog post on modular packages in AWS SDK for JavaScript

import * as AWS from "@aws-sdk/client-cognito-identity-provider";
const client = new AWS.CognitoIdentityProvider({ region: "REGION" });

// async/await.
try {
  const data = await client.listDevices(params);
  // process data.
} catch (error) {
  // error handling.
}

// Promises.
client
  .listDevices(params)
  .then((data) => {
    // process data.
  })
  .catch((error) => {
    // error handling.
  });

// callbacks.
client.listDevices(params, (err, data) => {
  // process err and data.
});

Troubleshooting

When the service returns an exception, the error will include the exception information, as well as response metadata (e.g. request id).

try {
  const data = await client.send(command);
  // process data.
} catch (error) {
  const { requestId, cfId, extendedRequestId } = error.$metadata;
  console.log({ requestId, cfId, extendedRequestId });
  /**
   * The keys within exceptions are also parsed.
   * You can access them by specifying exception names:
   * if (error.name === 'SomeServiceException') {
   *     const value = error.specialKeyInException;
   * }
   */
}

Getting Help

Please use these community resources for getting help. We use the GitHub issues for tracking bugs and feature requests, but have limited bandwidth to address them.

To test your universal JavaScript code in Node.js, browser and react-native environments, visit our code samples repo.

Contributing

This client code is generated automatically. Any modifications will be overwritten the next time the @aws-sdk/client-cognito-identity-provider package is updated. To contribute to client you can check our generate clients scripts.

License

This SDK is distributed under the Apache License, Version 2.0, see LICENSE for more information.

Client Commands (Operations List)

<summary> AddCustomAttributes </summary>

Command API Reference / Input / Output

<summary> AdminAddUserToGroup </summary>

Command API Reference / Input / Output

<summary> AdminConfirmSignUp </summary>

Command API Reference / Input / Output

<summary> AdminCreateUser </summary>

Command API Reference / Input / Output

<summary> AdminDeleteUser </summary>

Command API Reference / Input / Output

<summary> AdminDeleteUserAttributes </summary>

Command API Reference / Input / Output

<summary> AdminDisableProviderForUser </summary>

Command API Reference / Input / Output

<summary> AdminDisableUser </summary>

Command API Reference / Input / Output

<summary> AdminEnableUser </summary>

Command API Reference / Input / Output

<summary> AdminForgetDevice </summary>

Command API Reference / Input / Output

<summary> AdminGetDevice </summary>

Command API Reference / Input / Output

<summary> AdminGetUser </summary>

Command API Reference / Input / Output

<summary> AdminInitiateAuth </summary>

Command API Reference / Input / Output

<summary> AdminLinkProviderForUser </summary>

Command API Reference / Input / Output

<summary> AdminListDevices </summary>

Command API Reference / Input / Output

<summary> AdminListGroupsForUser </summary>

Command API Reference / Input / Output

<summary> AdminListUserAuthEvents </summary>

Command API Reference / Input / Output

<summary> AdminRemoveUserFromGroup </summary>

Command API Reference / Input / Output

<summary> AdminResetUserPassword </summary>

Command API Reference / Input / Output

<summary> AdminRespondToAuthChallenge </summary>

Command API Reference / Input / Output

<summary> AdminSetUserMFAPreference </summary>

Command API Reference / Input / Output

<summary> AdminSetUserPassword </summary>

Command API Reference / Input / Output

<summary> AdminSetUserSettings </summary>

Command API Reference / Input / Output

<summary> AdminUpdateAuthEventFeedback </summary>

Command API Reference / Input / Output

<summary> AdminUpdateDeviceStatus </summary>

Command API Reference / Input / Output

<summary> AdminUpdateUserAttributes </summary>

Command API Reference / Input / Output

<summary> AdminUserGlobalSignOut </summary>

Command API Reference / Input / Output

<summary> AssociateSoftwareToken </summary>

Command API Reference / Input / Output

<summary> ChangePassword </summary>

Command API Reference / Input / Output

<summary> CompleteWebAuthnRegistration </summary>

Command API Reference / Input / Output

<summary> ConfirmDevice </summary>

Command API Reference / Input / Output

<summary> ConfirmForgotPassword </summary>

Command API Reference / Input / Output

<summary> ConfirmSignUp </summary>

Command API Reference / Input / Output

<summary> CreateGroup </summary>

Command API Reference / Input / Output

<summary> CreateIdentityProvider </summary>

Command API Reference / Input / Output

<summary> CreateManagedLoginBranding </summary>

Command API Reference / Input / Output

<summary> CreateResourceServer </summary>

Command API Reference / Input / Output

<summary> CreateUserImportJob </summary>

Command API Reference / Input / Output

<summary> CreateUserPool </summary>

Command API Reference / Input / Output

<summary> CreateUserPoolClient </summary>

Command API Reference / Input / Output

<summary> CreateUserPoolDomain </summary>

Command API Reference / Input / Output

<summary> DeleteGroup </summary>

Command API Reference / Input / Output

<summary> DeleteIdentityProvider </summary>

Command API Reference / Input / Output

<summary> DeleteManagedLoginBranding </summary>

Command API Reference / Input / Output

<summary> DeleteResourceServer </summary>

Command API Reference / Input / Output

<summary> DeleteUser </summary>

Command API Reference / Input / Output

<summary> DeleteUserAttributes </summary>

Command API Reference / Input / Output

<summary> DeleteUserPool </summary>

Command API Reference / Input / Output

<summary> DeleteUserPoolClient </summary>

Command API Reference / Input / Output

<summary> DeleteUserPoolDomain </summary>

Command API Reference / Input / Output

<summary> DeleteWebAuthnCredential </summary>

Command API Reference / Input / Output

<summary> DescribeIdentityProvider </summary>

Command API Reference / Input / Output

<summary> DescribeManagedLoginBranding </summary>

Command API Reference / Input / Output

<summary> DescribeManagedLoginBrandingByClient </summary>

Command API Reference / Input / Output

<summary> DescribeResourceServer </summary>

Command API Reference / Input / Output

<summary> DescribeRiskConfiguration </summary>

Command API Reference / Input / Output

<summary> DescribeUserImportJob </summary>

Command API Reference / Input / Output

<summary> DescribeUserPool </summary>

Command API Reference / Input / Output

<summary> DescribeUserPoolClient </summary>

Command API Reference / Input / Output

<summary> DescribeUserPoolDomain </summary>

Command API Reference / Input / Output

<summary> ForgetDevice </summary>

Command API Reference / Input / Output

<summary> ForgotPassword </summary>

Command API Reference / Input / Output

<summary> GetCSVHeader </summary>

Command API Reference / Input / Output

<summary> GetDevice </summary>

Command API Reference / Input / Output

<summary> GetGroup </summary>

Command API Reference / Input / Output

<summary> GetIdentityProviderByIdentifier </summary>

Command API Reference / Input / Output

<summary> GetLogDeliveryConfiguration </summary>

Command API Reference / Input / Output

<summary> GetSigningCertificate </summary>

Command API Reference / Input / Output

<summary> GetUICustomization </summary>

Command API Reference / Input / Output

<summary> GetUser </summary>

Command API Reference / Input / Output

<summary> GetUserAttributeVerificationCode </summary>

Command API Reference / Input / Output

<summary> GetUserAuthFactors </summary>

Command API Reference / Input / Output

<summary> GetUserPoolMfaConfig </summary>

Command API Reference / Input / Output

<summary> GlobalSignOut </summary>

Command API Reference / Input / Output

<summary> InitiateAuth </summary>

Command API Reference / Input / Output

<summary> ListDevices </summary>

Command API Reference / Input / Output

<summary> ListGroups </summary>

Command API Reference / Input / Output

<summary> ListIdentityProviders </summary>

Command API Reference / Input / Output

<summary> ListResourceServers </summary>

Command API Reference / Input / Output

<summary> ListTagsForResource </summary>

Command API Reference / Input / Output

<summary> ListUserImportJobs </summary>

Command API Reference / Input / Output

<summary> ListUserPoolClients </summary>

Command API Reference / Input / Output

<summary> ListUserPools </summary>

Command API Reference / Input / Output

<summary> ListUsers </summary>

Command API Reference / Input / Output

<summary> ListUsersInGroup </summary>

Command API Reference / Input / Output

<summary> ListWebAuthnCredentials </summary>

Command API Reference / Input / Output

<summary> ResendConfirmationCode </summary>

Command API Reference / Input / Output

<summary> RespondToAuthChallenge </summary>

Command API Reference / Input / Output

<summary> RevokeToken </summary>

Command API Reference / Input / Output

<summary> SetLogDeliveryConfiguration </summary>

Command API Reference / Input / Output

<summary> SetRiskConfiguration </summary>

Command API Reference / Input / Output

<summary> SetUICustomization </summary>

Command API Reference / Input / Output

<summary> SetUserMFAPreference </summary>

Command API Reference / Input / Output

<summary> SetUserPoolMfaConfig </summary>

Command API Reference / Input / Output

<summary> SetUserSettings </summary>

Command API Reference / Input / Output

<summary> SignUp </summary>

Command API Reference / Input / Output

<summary> StartUserImportJob </summary>

Command API Reference / Input / Output

<summary> StartWebAuthnRegistration </summary>

Command API Reference / Input / Output

<summary> StopUserImportJob </summary>

Command API Reference / Input / Output

<summary> TagResource </summary>

Command API Reference / Input / Output

<summary> UntagResource </summary>

Command API Reference / Input / Output

<summary> UpdateAuthEventFeedback </summary>

Command API Reference / Input / Output

<summary> UpdateDeviceStatus </summary>

Command API Reference / Input / Output

<summary> UpdateGroup </summary>

Command API Reference / Input / Output

<summary> UpdateIdentityProvider </summary>

Command API Reference / Input / Output

<summary> UpdateManagedLoginBranding </summary>

Command API Reference / Input / Output

<summary> UpdateResourceServer </summary>

Command API Reference / Input / [Output](https://docs.aws.amazon.com/AWSJavaSc

changelog

Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

3.6.0 (2021-02-20)

Bug Fixes

  • revert publish v3.5.1-0 (#2058) (af25697)
  • client-kinesis-video-signaling: remove retry headers (#1963) (8b35943)
  • clients: remove unsupported CORS retry headers in new services (#2041) (82df9d3)
  • credential-provider-ini: refactor provider options interfaces (#2048) (34cecf1)
  • credential-provider-node: read config and credentials files only once (#2045) (7db14b1)
  • deps: add @aws-sdk/middleware-sdk-rds in DocDB and Neptune (#2042) (a0068f3)
  • lib-storage: fix typo in Upload.intialize (initialize) (#2025) (16214be)
  • middleware-sdk-ec2: add undeclared dependency @aws-sdk/protocol-http (#2043) (6e562ba)

Features

  • client-sso*: remove auth dependencies if client doesn't need (#2037) (f1e190c)
  • lib-storage: rewrite lib-storage upload (#2039) (2bd8f6a)

3.5.0 (2021-02-12)

Bug Fixes

  • util-dynamodb: state options.wrapNumbers on BigInt error in unmarshall (#2015) (d1c548e)
  • util-dynamodb: unmarshall small numbers or those in scientific notation (#2017) (80a8094)
  • util-user-agent-browser: use default import from bowser (#1991) (d2e8d4f)

Features

  • s3-request-presigner: automatically add host header (#1988) (cd50eeb)
  • util-dynamodb: marshall JavaScript Maps (#2010) (569b572)
  • util-dynamodb: support marshalling for Object.create (#1974) (a008d23)
  • add S3 and S3Control customizations for custom endpoints (#1993) (96c1b99)

3.4.1 (2021-01-29)

Bug Fixes

Features

  • use git-sync action to sync with private mirror (#1965) (10ab6a1)

3.4.0 (2021-01-28)

Bug Fixes

  • allow packages/types in gitignore (#1942) (b4b6fad)
  • credential-provider-cognito-identity: remove duplicate declarationDir (#1944) (d75488a)
  • generate-clients: call mergeManifest when constructor.name is Object (#1937) (601c03b)

Features

  • middleware-stack: allow adding middleware to override an existing one (#1964) (9c21f14), closes #1883
  • util-dynamodb: add option to convert class instance to map (#1969) (1783c69)
  • run prettier in parallel in generate-clients (#1949) (878617a)
  • use downlevel-dts to generate TS 3.4 compatible types (#1943) (63ad215)

3.3.0 (2021-01-14)

Bug Fixes

  • clients: export explicit dependencies on @aws-sdk/types (#1902) (96f1087)
  • clients: lowercase all header names in serializer (#1892) (1308721)
  • url-parser: merge browser and node url parser, add rn url parser (#1903) (99be092)
  • util-waiters: waiters should call operation once before entering waiting (#1915) (2a6ac11)

Features

  • clients: update README with documentation, usage and more (#1907) (03be111)

3.2.0 (2021-01-09)

Bug Fixes

  • lib-storage: chunk from readable only when defined (#1886) (4cdc08a)
  • s3-request-presigner: not to throw when get signed urls concurrently (#1884) (741bb99)
  • stop adding command mw repeatedly in resolveMiddleware() (#1883) (d4c302b)
  • readme: npm downloads tag (#1870) (1f8baf3)
  • readme: remove duplicate @aws-sdk (#1873) (85ae915)
  • readme: use latest for npm version badge in template (#1871) (80b57a7)
  • readme: use latest in npm version tag (#1872) (b8542d8)
  • util-user-agent-*: move @aws-sdk/types to devDependencies (#1879) (ea39ca6)
  • util-waiter: expose minDelay and maxDelay for waiters (#1839) (25cb359)

Features

  • use lock-threads GH action for inactive issues/PRs (#1881) (fc22682)
  • util-dynamodb: enable undefined values removal in marshall (#1840) (314d3b3)

3.1.0 (2020-12-23)

Bug Fixes

  • clients: default region and credential provider (#1834) (bc79ab5)
  • clients: populate sdkId in serviceId and default to use arnNamespace as signingName (#1786) (0011af2)
  • clients: remove retry headers for several services (#1789) (fc98d2d)
  • clients: update endpoint provider (#1824) (64d2210)
  • clients: use signing name from auth sigv4 trait (#1835) (e539302)
  • codegen: strip names from enums (#1837) (0711503)
  • lib-storage: cleanup stream listeners to prevent memory leak (3d36682)
  • middleware-user-agent: add middleware to final step of build (#1833) (e7dce39)
  • signature-v4: add secrets to signing key cache key (#1776) (8785ad4)
  • util-waiter: fix compiling error with waiter (#1812) (ca1f0d6), closes #1803
  • log requestId, extendedRequestId, cfId in $metadata (#1819) (f2a47e8)

Features

  • credential-provider-node: use credential_process from profile (#1773) (842e2a0), closes #1772
  • standardize user agent value (#1775) (388b180)
  • cucumber: use waiters in integration tests (#1792) (e151aee)
  • middleware-logger: log clientName, commandName, input, output (#1788) (4f9e56f)

3.0.0 (2020-12-15)

Features

1.0.0-rc.10 (2020-12-15)

Bug Fixes

Features

1.0.0-rc.9 (2020-12-11)

Bug Fixes

  • codegen: import SENSITIVE_STRING only when used (#1761) (9296283)
  • middleware-sdk-sqs: call next() exactly once in sendMessageMiddleware (#1752) (dc63e37)
  • shared-ini-file-loader: ignore prohibited profile name (#1764) (a209082)

Features

1.0.0-rc.8 (2020-12-05)

Bug Fixes

  • client-s3: fix union serialization (#1730) (6437e24)
  • client-sts: disable auth for public assumeRole commands (#1706) (891eae2)
  • codegen: checkstyle errors in AddBuiltinPlugins.java (#1731) (48c02f4)
  • middleware-sdk-sqs: Fix MD5 verification on SendMessageBatch. (#1666) (049f45e)
  • s3-request-presigner: skip hoisting SSE headers (#1701) (1ec70ff)

Features

  • update clients as of 11/20/2020 (#1711) (e932876)
  • update clients as of 11/30/2020 (#1734) (a1e8036)
  • update clients as of 12/3/2020 (#1741) (58383dc)
  • invalid-dependency: add invalidAsyncFunction which rejects with an Error (#1719) (c4c046e)

1.0.0-rc.7 (2020-11-20)

Bug Fixes

  • abort-controller: make AbortSignal WHATWG Spec compliant (#1699) (723ec4d)
  • codegen: add aws-iam-traits dependency (#1686) (d6fb1f6)
  • fetch-http-handler: omit body for HEAD/GET methods (#1698) (778b305)
  • node-http-handler: throw TimeoutError for Node.js timeouts (#1693) (96f61bb)
  • change paginators to export paginateOperationName (#1692) (6d02935)

Features

  • update clients as of 11/18/2020 (#1700) (8adfed1)
  • api-reference: add typedoc plugins for api reference (#1694) (2cb016f)
  • ci: add GitHub Action to test codegen (#1684) (41e9359)
  • node-http-handler: update timeout code and tests (#1691) (9e58bbb)
  • service-error-classification: add 429 response as Throttling (#1690) (9a62c0a)

BREAKING CHANGES

  • change paginators to export paginateOperationName to be consistent with verb nouns across AWS

1.0.0-rc.6 (2020-11-13)

Bug Fixes

Features

  • update clients as of 11/13 (#1676) (2d934c9)
  • codegen: add script to copy models from local directory (#1675) (028a362)

1.0.0-rc.5 (2020-11-09)

Bug Fixes

  • codegen for paginator send commands (#1667) (13f3347)
  • node-http-handler: set maxSockets above 0 in test (#1660) (706768d)
  • package.json: migrate @aws-sdk/types into devDependencies codegen (#1658) (eb50962)
  • migrate dev types for packages and lib into package.json devDeps (#1654) (16d7030)

Features

1.0.0-rc.4 (2020-10-31)

Bug Fixes

  • log requestId, extendedRequestId, cfId in metadata (#1640) (3a2f617)
  • client-timestream-*: use correct endpoint prefix (#1643) (f329821)
  • credential-provider-cognito-identity: return identityId as part of cognitoIdentityPool (#1635) (de75f7e)
  • util-format-url: remove headers or path from input (#1639) (db7aa08)

Features

1.0.0-rc.3 (2020-10-27)

Bug Fixes

  • client-cognito-identity: remove auth for UnlinkIdentity (#1621) (c32e5f3)
  • codegen: skip awsAuthPlugin when optionalAuth trait is set (#1622) (785272b)
  • generate-clients: Invoke prettier relative to client-generation (#1614) (a4136ab)

Features

  • polly-request-presigner: add presigned getSynthesizeSpeechUrl() (#1612) (2c9fd94)
  • update client description to add keywords (#1631) (93fc586)

1.0.0-rc.2 (2020-10-22)

Bug Fixes

  • storage: add version and downloads badges (#1599) (230d030)
  • throw 3XX redirection as errors explicitly (#1591) (76f83f1)

1.0.0-rc.1 (2020-10-19)

Bug Fixes

  • node-http-handler: fix type error sending Uint8Array as payload (#1561) (7bf03fc)

Features