AnkraDocs
Console

API reference · Access and identity

Password recovery

3 operations of the Ankra Cloud API: Password recovery by email - whether it is available, asking for a link, and setting a new password with one.

Whether password recovery by email is available#

GET/v1/auth/password-reset
Operation
get_password_reset_status
Credentials
None (public)

available is false when this deployment has no SMTP relay (ANKRA_CLOUD_SMTP_HOST); the portal then says recovery is unavailable instead of offering a form whose link would never arrive.

Responses

200The recovery status.application/json · PasswordResetStatus

200 response fields
FieldTypeDescription
availablerequiredbooleanFalse when this deployment cannot send email.
  • defaultAny other error, usually 500.

Example

bash
curl 'https://cloud.ankra.app/v1/auth/password-reset'

Email a link to set a new password#

POST/v1/auth/password-reset
Operation
send_password_reset_email
Credentials
None (public)

Always answers 202 with the same body, whether or not the address has an account, and whether or not mail is configured: nothing in the answer, its timing or its status says whether an account exists. For an address that has a user, a random 32-byte token (base64url) is issued, only its SHA-256 is stored, and <portal origin>/reset-password?token=<token> is emailed; the portal origin is the request's Origin when it is one of the configured portal origins (ANKRA_CLOUD_PORTAL_URLS), else the first. The link works once, for 30 minutes. At most 3 links are sent to one user per 15 minutes (further requests answer the same and send nothing). Rate limited per client network (5 a minute) and per email address (5 an hour), answering 429 for any address alike. Users without a password (signed up through an identity provider) can set one this way.

Request bodyapplication/json · PasswordResetRequest

Request body fields
FieldTypeDescription
emailrequiredstring (email)

Responses

202Accepted; if the address has an account, a link is on its way.application/json · PasswordResetAccepted

202 response fields
FieldTypeDescription
detailrequiredstring
  • 400The request is invalid; detail says why.
  • 429Rate limited or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/auth/password-reset' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string"
}'

Set a new password with the token from a reset link#

POST/v1/auth/password-reset/confirm
Operation
reset_password
Credentials
None (public)

Checks the token (looked up by its SHA-256; unused and unexpired), applies the signup password policy (12 to 1024 characters, not a known breached password), stores the argon2id hash, spends the token and every other open reset token of the user, ends every session and revokes every API token of the user, removes a TOTP second factor enrolled before the address was verified (with its recovery codes) and records user.password_reset in the account's audit log, all before answering 204. The reset verifies the address. The user then signs in with the new password. A refusal is a 400 problem with a stable reason: invalid_token, expired_token, used_token or weak_password (a refused password leaves the token usable). Rate limited per client network (10 a minute).

Request bodyapplication/json · PasswordResetConfirmation

Request body fields
FieldTypeDescription
tokenrequiredstringThe token query parameter of the reset link.
passwordrequiredstring

Responses

204The password is set and every session of the user has ended.

  • 400The token or the password was refused; reason says which way.
  • 429Rate limited or the email is locked out.
  • defaultAny other error, usually 500.

Example

bash
curl -X POST 'https://cloud.ankra.app/v1/auth/password-reset/confirm' \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "string",
  "password": "string"
}'