Ploy
Ploy
Authentication

Migrating to Ploy Auth

Map Supabase Auth and Clerk concepts and APIs to Ploy Auth.

Migrating to Ploy Auth

Ploy Auth covers the common auth building blocks with no separate service to run: users live in a database in your organization and sign-in runs on your app's domain. This page maps the concepts you know from Supabase Auth and Clerk.

From Supabase Auth

SupabasePloy Auth
auth.users tableploy_users in your auth database (Users and data)
auth.identitiesploy_identities
supabase.auth.signUp({ email, password })useAuth().signUp(email, password) or POST /_ploy/auth/signup
supabase.auth.signInWithPassword(...)useAuth().signIn(email, password) or POST /_ploy/auth/signin
supabase.auth.signInWithOAuth({ provider })useAuth().signInWithProvider("google") or /_ploy/auth/oauth/google
supabase.auth.getUser() on the servercurrentUser() from @meetploy/nextjs/auth, or env.PLOY_AUTH.getUser(token)
@supabase/ssr cookie clients and middlewareBuilt in: the ploy_session cookie is set by Ploy; use authMiddleware
Auth UI blocksSignInForm, SignUpForm or the hosted pages
supabase.auth.signInWithOtp({ email })Sign-in links or sign-in codes
supabase.auth.resetPasswordForEmail(...)Password reset via Forgot password? or /_ploy/auth/forgot-password
Provider settings in the Supabase dashboardDashboard → Auth → Settings
user_id uuid references auth.usersuser_id TEXT REFERENCES ploy_users(id) in the same database, or an ID reference in a separate database; see Referencing users

Differences to plan for:

  • No row-level security. Access rules live in your server code: resolve the user with currentUser() or PLOY_AUTH, then filter by user_id.
  • Foreign keys need the same database. Store application tables alongside ploy_users for enforced references and SQL joins; see sharing the auth database. If you choose a separate database, reference users by ID and clean up application rows yourself when deleting a user.
  • Auth emails need a sending domain. Email verification, sign-in links and codes, and password reset are sent with Ploy Email; see Emails, sign-in links and passwords.
  • Not yet available: phone sign-in and MFA.

From Clerk

ClerkPloy Auth
<ClerkProvider><AuthProvider> from @meetploy/auth-react
<SignIn />, <SignUp /><SignInForm />, <SignUpForm />
<UserButton /><UserButton />
<UserProfile /><UserProfile />
<SignedIn>, <SignedOut><SignedIn>, <SignedOut> (client in auth-react, server in @meetploy/nextjs/auth)
appearance={{ variables }}appearance={{ variables }} (Theming)
clerkMiddleware() + createRouteMatcher()authMiddleware({ protectedRoutes }) + createRouteMatcher()
auth(), currentUser()auth(), currentUser() from @meetploy/nextjs/auth
auth.protect()protect()
Account PortalHosted pages on your own domain
user.publicMetadatauser.metadata, set at sign-up

Differences to plan for:

  • Middleware checks presence, not validity. Clerk verifies sessions in middleware; Ploy's middleware only checks the cookie, so confirm the user with currentUser() or protect() in the page.
  • Email verification is built in. Ploy Auth sends verification, sign-in link or code, and password reset emails; Require email verification is on by default for new setups to keep unverified users out, and can be turned off under Auth → Settings → Emails. See Emails, sign-in links and passwords.
  • Not yet available: organizations, MFA, phone verification, and impersonation.

Moving existing users

Organization owners and admins can import existing users, keeping the user IDs referenced by their application data. Deploy the production project with auth configured first, and wait for its auth database to be initialized.

Create a private JSON file with a users array, then import it using the auth binding ID, project ID, or project name. The CLI requires the organization ID explicitly:

ploy api auth list --org <orgId>
ploy api auth import my-project --org <orgId> --file users.json
users.json
{
	"users": [
		{
			"id": "existing-user-id",
			"email": "person@example.com",
			"emailVerified": true,
			"identities": [
				{
					"provider": "google",
					"providerUserId": "existing-google-subject",
					"email": "person@example.com",
					"emailVerified": true
				}
			]
		}
	]
}

The API equivalent is POST /orgs/{orgId}/auth-bindings/{authBindingId}/users/import with the same JSON body. Each request accepts 1–100 users, up to 3 social identities per user, and at most 512 KiB. A successful response is { "imported": 1 }. Emails are trimmed and lowercased; IDs are preserved exactly. All users and identities in one request are inserted atomically. A conflicting user ID, email, or provider account returns 409 and leaves the whole batch unchanged; imports never overwrite or merge accounts. Larger migrations must be split into separate batches, which are not atomic as a group.

Passwords from Better Auth

Map Better Auth's user.id, user.email, and user.emailVerified directly. Read password hashes from the user's credential account, not from the user row. For social accounts, providerUserId is the source account's accountId (the provider's user ID), not its database row id; provider corresponds to providerId. Do not import credential accounts as social identities.

Better Auth's default scrypt hashes can be reused without knowing users' passwords or asking them to reset. Include the exported passwordHash and "passwordHashFormat": "better-auth" for each password user. This format supports the native <32-character hex salt>:<128-character hex key> hash using scrypt N=16384, r=16, p=1, a 64-byte key, and NFKC-normalized passwords. Custom Better Auth hashing functions need their own compatibility review.

Ploy preserves the salt as the original UTF-8 hex string and stores an explicitly tagged scrypt value. The original password continues to work. After the first successful password sign-in, Ploy upgrades the hash to its current password hashing configuration, without changing the user's ID. Raw colon-separated hashes require the explicit source format because older Ploy PBKDF2 hashes use the same syntax.

Already-tagged scrypt$N$r$p$salt$key hashes use "passwordHashFormat": "ploy" (the default). Both the salt and key are unpadded base64url; the salt must be 16–64 bytes and the key 64 bytes. Import rejects invalid parameters, memory requirements above 64 MiB, and work above four times Ploy's default N*r*p. Verification uses the parameters encoded in each imported hash rather than treating all scrypt hashes as the same configuration. Other algorithms such as bcrypt are not supported by this import; use password reset or another sign-in method instead.

Social sign-in and cutover

Use the provider's stable user ID, not the source auth system's account-row ID. Enable the matching Google, Apple, or GitHub provider in Ploy with compatible OAuth application credentials; merely importing an identity does not enable that provider. Only mark emails verified if the source system actually verified them.

If Google or GitHub OAuth credentials already exist in the same project's environment variables, an organization owner or admin can copy them server-side without exposing their secret values:

POST /orgs/{orgId}/auth-bindings/{authBindingId}/providers/google/import-env
{
	"clientIdKey": "GOOGLE_CLIENT_ID",
	"clientSecretKey": "GOOGLE_CLIENT_SECRET"
}

Use github in the path with GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET for GitHub. Only these exact provider-specific key pairs are accepted; unrelated secrets cannot be copied into the publicly readable client ID field. The source is the binding's own project environment, the same values used for production; callers cannot select another project or preview. The response only confirms the provider, enabled state, and that a secret is present. Existing provider rows are left unchanged unless "overwrite": true is explicitly included. Imported providers default to disabled; configure their callback URL for Ploy before enabling them in Auth → Settings, or explicitly include "enabled": true at cutover. Apple credentials must be configured separately.

Imports do not copy active sessions, provider access or refresh tokens, granted scopes, passkeys, timestamps, or profile metadata. Configure additional scopes in the dashboard; imported identities return null from getProviderToken until users sign in with the provider again. Freeze source account changes during the final export/import to avoid missing users or password changes, test a small batch first, and retain a source backup for rollback. Importing users works while Allow sign-ups is off; that setting only controls new self-service registrations.

Password hashes are sensitive credentials. Keep export files outside source control, restrict file permissions, and delete them securely when migration is complete. Never include real hashes in logs, issues, or support messages.

How is this guide?

Last updated on