Auth Integration
Integrate Lumen with your authentication provider
Automatic Plan Assignment
For entitlements to work properly, all users need to have a plan assigned. The best way to do this is automatically assigning your free plan to new users when they sign up.
Supported providers
We support Clerk, Supabase, and Better Auth out of the box. Follow the Setup page for each provider to get started. You will need to setup the backend proxy and forward webhooks for your auth provider.
Other providers
For providers not supported out of the box, call Lumen when a user is created to auto-assign your free plan (or a specific plan via Enrollment Rules).
Use the Server SDK:
import { enrollUser } from "@getlumen/server";
await enrollUser({
email: user.email,
name: user.name,
userId: user.id,
});What happens:
- If an Enrollment Rule matches the email/domain, that plan is assigned
- Otherwise the latest free plan from your active pricing tables is assigned
Auth0
Create an Auth0 Action that runs on user registration:
exports.onExecutePostUserRegistration = async (event) => {
const { user } = event;
await fetch("https://api.getlumen.dev/v1/enrollment/enroll", {
method: "POST",
headers: {
Authorization: `Bearer ${event.secrets.LUMEN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
customerEmail: user.email,
customerName: user.name || user.nickname,
userId: user.user_id,
}),
});
};Add LUMEN_API_KEY to your Auth0 Action secrets.
NextAuth.js
Use the events callback to enroll users after OAuth signin:
// auth.ts or [...nextauth].ts
import NextAuth from "next-auth"
import { enrollUser } from "@getlumen/server"
export default NextAuth({
// ... your providers
events: {
async signIn({ user, isNewUser }) {
if (isNewUser) {
await enrollUser({
email: user.email!,
name: user.name || "",
userId: user.id,
});
}
},
},
})For Auth.js v5:
// auth.ts
import NextAuth from "next-auth"
import { enrollUser } from "@getlumen/server"
export const { handlers, signIn, signOut, auth } = NextAuth({
// ... your providers
events: {
async signIn({ user, isNewUser }) {
if (isNewUser) {
await enrollUser({
email: user.email!,
name: user.name || "",
userId: user.id,
});
}
},
},
})Testing
Test your integration:
- Create a test user in your app
- Check the Lumen dashboard for the new customer
- Verify a subscription was created