Password authentication
Register an auth record, sign in with a password, refresh a token, and handle invalid credentials.
Use password authentication when your auth collection manages a user identity and password. You need an auth collection with Identity/Password enabled, a configured identity field with a unique index, and a client initialized for your PocketBase URL.
By the end of this guide, the client can create a user, establish an authenticated session, refresh that session in the same collection context, and report invalid credentials without revealing whether an identity exists. Begin with a development collection and a synthetic identity such as reader@example.com.
Authenticate a user
Create a record in your auth collection with an identity value and password. Use a reserved example address in development.
const user = await pb.collection("users").create({
email: "reader@example.com",
password: "use-a-local-test-password",
passwordConfirm: "use-a-local-test-password",
});The create request returns the new auth record when the collection validation succeeds.
Call authWithPassword with the identity and password.
const authData = await pb.collection("users").authWithPassword(
"reader@example.com",
"use-a-local-test-password",
);
console.log(pb.authStore.isValid, pb.authStore.record.id);PocketBase stores the returned token and record in the client auth store. isValid is true after a successful sign-in.
When the client has a valid auth state, call the refresh operation before continuing a long-lived session.
const refreshed = await pb.collection("users").authRefresh();
console.log(refreshed.token);The response supplies refreshed authentication data for the same auth collection context.
Catch authentication errors without revealing whether an identity exists.
try {
await pb.collection("users").authWithPassword(identity, password);
} catch (error) {
if (error.response?.message === "Failed to authenticate.") {
showSignInError("The identity or password is incorrect.");
return;
}
throw error;
}Invalid credentials produce the generic Failed to authenticate. error. Keep that message generic in the UI.
pb.authStore.isValid and using the returned auth record for a request whose API rule permits the authenticated user.The verification request should use the same pb instance and auth collection as the sign-in call. A true isValid value confirms the client accepted the returned authentication data; the permitted request confirms that the session can be used where the collection rules allow it.
Limitations and recovery
If sign-in fails for every valid password, check that the collection is an auth collection, Identity/Password is enabled, the submitted identity field is allowed, and its value has a unique index. If the refresh request is rejected, authenticate again instead of retrying an invalid or missing auth state.
When handling a failed sign-in, preserve the generic Failed to authenticate. response in the user-facing message. Check the collection configuration and identity field before changing application code. If the identity field is not unique, correct that collection configuration and retry registration with a value that satisfies its validation.
Next steps
Define access with API rules and filters, or learn the alternative One-time-password authentication.