Skip to main content

Password recovery

Password recovery uses a short-lived code bound to the project, email address and account.

Request recovery code​

MutationdocumentId: sendPasswordRecoveryEmailauth: public

sendPasswordRecoveryEmail​

Description​

Sends a short-lived recovery code when the email belongs to an account. Registered and unknown addresses receive the same successful API response.

A repeated request for the same email during the cooldown returns the same successful result without creating another code or email.

Input​

FieldTypeRequiredDescription
emailString!✓Master account email

Result​

Response type - OperationResult.

Errors​

  • RECOVERY_EMAIL_DISABLED - email recovery is disabled for the project.
  • TOO_MANY_ATTEMPTS - one IP submitted too many recovery requests.

For an IP restriction, extensions.retryAfterSeconds contains the retry delay.

Exchange example​

Request
documentId: sendPasswordRecoveryEmail
{
  "documentId": "sendPasswordRecoveryEmail",
  "variables": {
    "email": "[email protected]"
  }
}
Response
200 OK
{
  "data": {
    "sendPasswordRecoveryEmail": {
      "message": "Recovery code sent"
    }
  }
}
OperationResult

Confirm recovery​

MutationdocumentId: confirmPasswordRecoveryCodeauth: public

confirmPasswordRecoveryCode​

Description​

Verifies the recovery code bound to the email address and replaces the master account password.

Input​

FieldTypeRequiredDescription
emailString!✓Master account email
codeString!✓Recovery code
newPasswordString!✓New password

Result​

Response type - UserResult, containing the updated user and a message.

Errors​

  • RECOVERY_EMAIL_DISABLED - email recovery is disabled for the project.
  • INVALID_CODE - the code is invalid or expired.
  • TOO_MANY_ATTEMPTS - the verification attempt limit was exceeded.
  • PASSWORD_TOO_WEAK - the new password is present in the compromised password database.

An unknown email and an invalid, expired, consumed code produce the same INVALID_CODE response. For throttled verification, extensions.retryAfterSeconds contains the retry delay.

Verification attempts are limited independently for the IP and the IP plus email pair. There is no global email lock, so attempts from another address cannot block the owner from applying a valid code.

Exchange example​

Request
documentId: confirmPasswordRecoveryCode
{
  "documentId": "confirmPasswordRecoveryCode",
  "variables": {
    "email": "[email protected]",
    "code": "A1B2-C3D4-E5F6-7890",
    "newPassword": "Recovered26!"
  }
}
Response
200 OK
{
  "data": {
    "confirmPasswordRecoveryCode": {
      "user": {
        "id": "1001",
        "email": "[email protected]"
      },
      "message": "Password changed"
    }
  }
}
ConfirmRecoveryCodeInputUserResult