Verification, password reset, and email change
Implement token-based account verification, password recovery, and email changes for an auth collection.
These flows let users verify an email address, recover a password, or replace an email address without exposing tokens in application logs. Each flow starts with a request endpoint and finishes when the user submits the token from the message.
Before you begin
- Use an auth collection such as
users. - Configure PocketBase mail delivery and templates before testing message-based flows.
- Treat tokens as secrets. Pass them only to the matching confirmation endpoint.
- The authenticated user must request an email change; the request route requires the same collection context authentication.
Account lifecycle
Steps
Call POST /api/collections/users/request-verification with the user's email. PocketBase rate-limits repeated verification requests.
curl -X POST http://127.0.0.1:8090/api/collections/users/request-verification \
-H 'Content-Type: application/json' \
-d '{"email":"person@example.com"}'PocketBase sends the verification message when the request is accepted. Use the link or token from that message in the next step.
Submit the token to POST /api/collections/users/confirm-verification:
curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-verification \
-H 'Content-Type: application/json' \
-d '{"token":"TOKEN_FROM_EMAIL"}'The account's verification state changes when the token is valid and belongs to the requested collection.
Ask PocketBase to send a reset message:
curl -X POST http://127.0.0.1:8090/api/collections/users/request-password-reset \
-H 'Content-Type: application/json' \
-d '{"email":"person@example.com"}'The request is rate-limited. Do not treat the response as proof that an account exists; show a neutral message in the application.
Send the reset token and the new password to POST /api/collections/users/confirm-password-reset:
curl -X POST http://127.0.0.1:8090/api/collections/users/confirm-password-reset \
-H 'Content-Type: application/json' \
-d '{"token":"TOKEN_FROM_EMAIL","password":"Use-a-new-long-password","passwordConfirm":"Use-a-new-long-password"}'PocketBase changes the password only when the token is valid and unexpired. Require the user to sign in again after recovery.
With the user's current auth token, request an email change:
curl -X POST http://127.0.0.1:8090/api/collections/users/request-email-change \
-H 'Authorization: USER_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"newEmail":"new-person@example.com"}'After the user receives the confirmation message, submit its token to POST /api/collections/users/confirm-email-change. A successful response confirms the new address.
Troubleshoot token errors
An invalid or expired token is rejected by the confirmation handler. Request a new message and use only its newest token. A token from another auth collection is also rejected because the token is checked against the collection context. If repeated requests are rejected, wait for the endpoint rate limit and avoid retry loops.
Next step
Review MFA and user impersonation before adding privileged authentication workflows.