Users and clients

Password authentication

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 the auth record

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.

Refresh the token

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.

Handle failed credentials

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.

✅Verify success by checking 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.