InitiatePointInTimeRecovery - Amazon Cognito User Pools
Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

InitiatePointInTimeRecovery

Initiates a point-in-time recovery of a user pool to a time in the past that you specify. This operation is the first step of a recovery and doesn't change your user pool data. Amazon Cognito pauses write operations in the user pool and generates a recovery preview, which might not be available immediately. The preview shows the number of entities that the recovery creates, updates, and deletes. To check the status of the recovery and review the preview, make a DescribePointInTimeRecovery request. When the status is PREVIEW_GENERATED, apply the recovery with a StartPointInTimeRecovery request or discard it with a CancelPointInTimeRecovery request. The time that it takes to generate the recovery preview doesn't depend on the size of your user pool.

Important

Point-in-time recovery is a disaster recovery feature. Use it to recover from accidental or unauthorized changes that affect your user data, for example the deletion or corruption of many users. Don't use point-in-time recovery to remove users that were created recently or to revert changes to individual users. To delete or update individual users, use operations like AdminDeleteUser and AdminUpdateUserAttributes.

While a recovery is in progress, Amazon Cognito blocks operations that write to the user pool, for example user sign-up, user creation, and attribute updates. Sign-in and read operations continue to work, with the following exceptions:

  • Users who must set a new password, set up MFA, or respond to a TOTP MFA challenge can't complete sign-in. Sign-in with the NEW_PASSWORD_REQUIRED, MFA_SETUP, and SOFTWARE_TOKEN_MFA challenges fails until the recovery ends.

  • Federated users can sign in only if they have previously signed in to the user pool and their attributes from the external identity provider haven't changed.

  • You can't create or start user import jobs. Start your import jobs after the recovery ends.

If you don't start or cancel the recovery within 24 hours after you initiate it, the recovery preview expires. Amazon Cognito then resumes write operations and doesn't change your user pool data. The 24-hour period includes the time that Amazon Cognito takes to generate the recovery preview.

A point-in-time recovery restores user data, including user profiles and attributes, group memberships, passwords, MFA settings, and passkeys. It doesn't restore user pool configuration, for example app clients, the attribute schema, encryption settings, or multi-Region replication settings. Users who changed their password after the recovery point keep their current password.

The following requirements and limits apply to point-in-time recovery:

  • Your user pool must be on the Essentials or Plus feature plan. With the Essentials feature plan, you can recover your user pool to a point in time up to 1 day in the past. With the Plus feature plan, you can recover up to 14 days in the past. Your user pool must have been on the required feature plan at the recovery point. For example, to recover to a point in time 14 days ago, your user pool must have been on the Plus feature plan for the past 14 days.

  • The recovery point must be at least 15 minutes in the past and can't be earlier than the creation time of the user pool.

  • A user pool can have only one active recovery at a time.

  • An AWS account can have up to five active recoveries at a time across all of its user pools. An organization in AWS Organizations can have up to ten active recoveries at a time across all of its accounts.

  • You can complete one recovery of a user pool in a 24-hour period.

  • You can create up to three recovery previews of a user pool, ten recovery previews in an AWS account, and 15 recovery previews in an organization in AWS Organizations in a 24-hour period. You can create up to ten recovery previews of a user pool in a 30-day period.

  • You can't initiate a recovery while a user import job is in progress in your user pool. Wait for the import job to complete, or stop it with a StopUserImportJob request, and then initiate the recovery.

  • In a user pool with multi-Region replication, you can initiate a recovery only in the primary AWS Region, and only after replication is complete.

  • If your user pool uses a customer managed key in AWS KMS for encryption, the key must remain enabled and accessible to Amazon Cognito for the duration of the recovery.

  • Some user pools don't support point-in-time recovery, for example some older user pools and user pools that contain user data with characters or formats that point-in-time recovery doesn't support. If your user pool doesn't support it, Amazon Cognito returns an error when you initiate a recovery. To get help with this limitation, contact AWS Support.

Note

Amazon Cognito evaluates AWS Identity and Access Management (IAM) policies in requests for this API operation. For this operation, you must use IAM credentials to authorize requests, and you must grant yourself the corresponding IAM permission in a policy.

Request Syntax

{ "RestoreTimestamp": number, "UserPoolId": "string" }

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

RestoreTimestamp

The point in time that you want to recover your user pool to. Amazon Cognito reverts changes to user data that occurred after this time. The recovery point must be at least 15 minutes in the past and within the recovery period of your user pool feature plan: up to 1 day in the past with the Essentials feature plan, or up to 14 days in the past with the Plus feature plan.

Type: Timestamp

Required: Yes

UserPoolId

The ID of the user pool that you want to recover.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 55.

Pattern: [\w-]+_[0-9a-zA-Z]+

Required: Yes

Response Syntax

{ "Restoration": { "RestoreId": "string", "RestorePreview": [ { "CreateCount": number, "DeleteCount": number, "Entity": "string", "UpdateCount": number } ], "RestoreStatus": "string", "RestoreTimestamp": number, "TriggerTimestamp": number } }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Restoration

The details of the recovery that you initiated. Includes the recovery ID that you can use in later requests to describe, start, or cancel the recovery.

Type: RestorationType object

Errors

For information about the errors that are common to all actions, see Common Error Types.

ConcurrentModificationException

This exception is thrown if two or more modifications are happening concurrently.

message

The message provided when the concurrent exception is thrown.

HTTP Status Code: 400

FeatureUnavailableInTierException

This exception is thrown when a feature that you attempted to use or configure isn't included in your user pool's current feature plan. This can occur when:

  • You configure a feature that your feature plan doesn't support.

  • You make a request that uses a feature that requires a higher feature plan.

To resolve this issue, upgrade your user pool to a feature plan that includes the feature.

HTTP Status Code: 400

InternalErrorException

This exception is thrown when Amazon Cognito encounters an internal error.

message

The message returned when Amazon Cognito throws an internal error exception.

HTTP Status Code: 500

InvalidParameterException

This exception is thrown when the Amazon Cognito service encounters an invalid parameter.

message

The message returned when the Amazon Cognito service throws an invalid parameter exception.

reasonCode

The reason code of the exception.

HTTP Status Code: 400

LimitExceededException

This exception is thrown when a user exceeds the limit for a requested AWS resource.

message

The message returned when Amazon Cognito throws a limit exceeded exception.

HTTP Status Code: 400

NotAuthorizedException

This exception is thrown when a user isn't authorized.

message

The message returned when the Amazon Cognito service returns a not authorized exception.

HTTP Status Code: 400

OperationNotEnabledException

This exception is thrown when an operation is not available in the current region or for the current user pool configuration. This can occur when attempting to perform operations that are not supported in secondary replica regions.

HTTP Status Code: 400

ResourceNotFoundException

This exception is thrown when the Amazon Cognito service can't find the requested resource.

message

The message returned when the Amazon Cognito service returns a resource not found exception.

HTTP Status Code: 400

TooManyRequestsException

This exception is thrown when the user has made too many requests for a given operation.

message

The message returned when the Amazon Cognito service returns a too many requests exception.

HTTP Status Code: 400

Examples

Example

The following example request initiates a point-in-time recovery of a user pool on the Plus feature plan to its state on October 7, 2026 at 12:00 UTC, about 27 hours before the request. Amazon Cognito pauses write operations in the user pool. The status of the recovery is PREVIEW_GENERATING until the recovery preview is available.

Sample Request

POST HTTP/1.1 Host: cognito-idp.us-west-2.amazonaws.com X-Amz-Date: 20230613T200059Z Accept-Encoding: gzip, deflate, br X-Amz-Target: AWSCognitoIdentityProviderService.InitiatePointInTimeRecovery User-Agent: <UserAgentString> Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature> Content-Length: <PayloadSizeBytes> { "RestoreTimestamp": 1791374400, "UserPoolId": "us-east-1_EXAMPLE" }

Sample Response

HTTP/1.1 200 OK Date: Tue, 13 Jun 2023 20:00:59 GMT Content-Type: application/x-amz-json-1.0 Content-Length: <PayloadSizeBytes> x-amzn-requestid: a1b2c3d4-e5f6-a1b2-c3d4-EXAMPLE11111 Connection: keep-alive { "Restoration": { "RestoreId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "RestoreStatus": "PREVIEW_GENERATING", "RestoreTimestamp": 1791374400, "TriggerTimestamp": 1791473400 } }

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: