Users and clients

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

Request verification

Call POST /api/collections/users/request-verification with the user's email. PocketBase rate-limits repeated verification requests.

bash

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.

Confirm verification

Submit the token to POST /api/collections/users/confirm-verification:

bash

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.

Request a password reset

Ask PocketBase to send a reset message:

bash

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.

Confirm the new password

Send the reset token and the new password to POST /api/collections/users/confirm-password-reset:

bash

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.

Request and confirm an email change

With the user's current auth token, request an email change:

bash

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.

✅Verify success by fetching the auth record and checking the expected verification or email value, then require a fresh authentication if the password changed.

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.