Migrate from Users & Permissions
This guide moves an existing Strapi app from the built-in Users & Permissions (U&P) plugin to Better Auth + API Permissions, without forcing your users to reset their passwords.
The migration runs automatically at boot while both plugins are installed: it
reads your U&P users, credentials, roles and permissions, and writes them into
Better Auth's user/account content types and API Permissions roles.
The migration writes new records based on your existing data. Take a database backup (or run against a copy) before you start, and use dry run (below) to preview the result.
How passwords are handled
U&P hashes passwords with bcrypt; Better Auth defaults to scrypt. The
migration copies your bcrypt hashes verbatim into Better Auth's account table,
and a small compatibility layer keeps them working:
- Existing bcrypt hashes are verified with bcrypt.
- On the next successful sign-in, that user's password is transparently re-hashed to scrypt (Better Auth's default).
No password resets are required.
Prerequisites
@strapi-community/plugin-better-authinstalled and enabled.- A Better Auth config (
auth.ts) — see Getting started. - The U&P plugin still installed (it is removed at the end).
@strapi-community/plugin-api-permissionsinstalled only if you use it for Content API role-based permissions and want those role and permission assignments migrated. It is optional — without it, users and credentials are still migrated and the role/permission steps are simply skipped.
Step 1 — Enable migration mode
Normally Better Auth refuses to boot alongside U&P. Enable the migration
option to allow them to run together for the migration:
export default {
'better-auth': {
enabled: true,
config: {
migration: {
enabled: true,
// Preview only — logs what would happen and writes nothing.
dryRun: false,
},
},
},
};
You can also enable it with the BETTER_AUTH_MIGRATE_FROM_USERS_PERMISSIONS=true
environment variable.