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#
/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
| Field | Type | Description |
|---|---|---|
availablerequired | boolean | False when this deployment cannot send email. |
- defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/auth/password-reset'Email a link to set a new password#
/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
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) |
Responses
202Accepted; if the address has an account, a link is on its way.application/json · PasswordResetAccepted
| Field | Type | Description |
|---|---|---|
detailrequired | string |
- 400The request is invalid;
detailsays why. - 429Rate limited or the email is locked out.
- defaultAny other error, usually 500.
Example
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#
/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
| Field | Type | Description |
|---|---|---|
tokenrequired | string | The token query parameter of the reset link. |
passwordrequired | string |
Responses
204The password is set and every session of the user has ended.
- 400The token or the password was refused;
reasonsays which way. - 429Rate limited or the email is locked out.
- defaultAny other error, usually 500.
Example
curl -X POST 'https://cloud.ankra.app/v1/auth/password-reset/confirm' \
-H 'Content-Type: application/json' \
-d '{
"token": "string",
"password": "string"
}'