16.1.1.20. Recover endpoints

The password recovery REST API lets a user request and consume a one-time recovery code in order to reset their password. It is only useful for users in editable user stores; the user-scope policy password_reset must be active for the user.

Sending the recovery code requires a working email transport: the server config key recovery.identifier must point to a configured SMTP server (see SMTP server configuration).

The endpoints are anonymous (no auth header).

POST /recover

Request a one-time password recovery code for a user. The recovery code is sent by email to the address stored for that user; it expires after one hour.

The server must have recovery.identifier configured to a working SMTP server, the user must live in an editable user store, and the user-scope policy password_reset must be active. The email form field has to match the user’s stored email address (case-insensitive); otherwise the request is rejected.

The recovery link is built from the configured PI_BASE_URL (see pi.cfg). If PI_BASE_URL is not configured, this endpoint refuses to operate.

This endpoint is anonymous — no authentication header is required.

JSON Parameters:

  • user – login name of the user (required).

  • realm – realm of the user (required if the user is not in the default realm).

  • email – the user’s email address (required).

Status Codes:

  • 200 OK – True on success; failures raise a JSON error response.

POST /recover/reset

Consume a recovery code (previously obtained via POST /recover) and set a new password for the user. The recovery code is bound to a specific user, so the request must identify the same user that requested the code.

The user-scope policy password_reset must be active. This endpoint is anonymous — no authentication header is required.

JSON Parameters:

  • user – login name of the user (required).

  • realm – realm of the user (required if the user is not in the default realm).

  • recoverycode – the one-time code that was emailed to the user (required).

  • password – the new password to set for the user (required).

Status Codes:

  • 200 OK – result.value is True if the password was changed, False if the recovery code was invalid or expired.