Authentication API reference
Reference auth-collection endpoints for tokens, OAuth2, OTP, verification, recovery, email changes, and impersonation.
Authentication endpoints operate on an auth collection at /api/collections/{collection}. Send the resulting token as Authorization: <token> on later requests. PocketBase is stateless: discard the token locally to sign out. The _superusers collection does not support OAuth2; impersonation is restricted to superusers.
Endpoint summary
The following operations are available for an auth collection. Each operation is rate-limited by its named authentication action; collection API rules and the auth method options still apply.
| Method | Path | Purpose | Authorization |
|---|---|---|---|
GET | /auth-methods | List enabled auth methods and OAuth2 providers. | Public, subject to collection configuration. |
POST | /auth-refresh | Refresh the current auth record token. | Current token from the same collection. |
POST | /auth-with-password | Authenticate with identity and password. | Public when enabled. |
POST | /auth-with-oauth2 | Exchange an OAuth2 provider code. | Public when provider is enabled; not supported for _superusers. |
POST | /request-otp | Request an email OTP. | Public when OTP is enabled. |
POST | /auth-with-otp | Exchange an OTP for an auth token. | Public when OTP is enabled. |
POST | /request-password-reset | Send a password-reset email. | Public when enabled. |
POST | /confirm-password-reset | Apply a reset token and new password. | Reset token in the request. |
POST | /request-verification | Send a verification email. | Current token from the same collection. |
POST | /confirm-verification | Confirm an email token. | Verification token in the request. |
POST | /request-email-change | Start an email change. | Current token from the same collection. |
POST | /confirm-email-change | Confirm an email-change token. | Confirmation token in the request. |
POST | /impersonate/{id} | Create a non-renewable token for a user record. | Superuser token. |
Common request and response behavior
Requests use Content-Type: application/json unless you send form data. Collection paths accept a collection name or ID. Successful authentication responses contain a token and the authenticated record; refresh returns a replacement token and record data. Failed requests use the standard error shape:
{ "status": 400, "message": "...", "data": {} }Use status 401 for missing or invalid credentials, 403 when the authenticated account is not permitted, 404 when the collection is not an auth collection or the resource is absent, and 400 for invalid payloads, expired tokens, or disabled methods. The exact validation details appear under data.
Password, OTP, and OAuth2 operations
/auth-with-password accepts the configured identity field and password. /request-otp accepts the auth record email and returns an otpId; /auth-with-otp accepts otpId and the received OTP. When multi-factor authentication is enabled, include the mfaId returned by the first authentication attempt in the second method request.
/auth-with-oauth2 accepts provider, code, and the provider's codeVerifier and redirect URL for a manual code exchange. The provider must be configured and enabled. The global /api/oauth2-redirect endpoint accepts both GET and POST provider callbacks. An unknown or disabled provider fails validation.
Recovery and account lifecycle operations
/request-password-reset accepts an email address. /confirm-password-reset accepts the reset token, the new password, and its confirmation. /request-verification sends a message for the current auth record; /confirm-verification accepts the verification token. /request-email-change accepts the new email and requires the current auth context; /confirm-email-change accepts the confirmation token.
POST /api/collections/{collection}/impersonate/{id}
This operation returns a token for the target auth record. The token can have a custom duration, is not renewable, and must be treated as a privileged credential when the caller impersonates a superuser.
/api/collections/{collection}/impersonate/{id}Superuser authorization token.
Auth collection name or ID.
Target auth record ID.
Optional token duration in seconds.
curl --request POST \
--url http://127.0.0.1:8090/api/collections/users/impersonate/RECORD_ID \
--header 'Authorization: SUPERUSER_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"duration": 3600
}'The response contains the target record and non-renewable token.
For complete workflows, see password authentication, one-time-password authentication, OAuth2 authentication, verification, password reset, and email change, and MFA and user impersonation.