⚡ BolkAuth

HTTP Routes

Assuming the handler is mounted at /api/auth:

MethodRouteDescription
POST/api/auth/sign-upCreate a user with email and password.
POST/api/auth/sign-in/emailSign in with email and password.
POST/api/auth/sign-in/magic-linkSend a magic-link email.
GET/api/auth/verifyVerify a magic-link token.
GET/api/auth/oauth/:providerStart OAuth provider redirect.
GET/api/auth/oauth/:provider/callbackHandle OAuth provider callback.
POST/api/auth/otp/sendSend an email OTP code.
POST/api/auth/otp/verifyVerify an OTP code and create a session.
POST/api/auth/sign-outDelete the session and clear the cookie.
GET/api/auth/sessionReturn the current session and user.
GET/api/auth/user/metadata?key=...Read one metadata key.
POST/api/auth/user/metadataUpdate metadata keys.
POST/api/auth/onboarding/stepPersist an onboarding step payload.
POST/api/auth/onboarding/completeMark onboarding complete in metadata.

Config Shape

interface BolkAuthConfig {
  adapter: BolkAuthAdapter;
  secret: string;
  session?: SessionConfig;
  email?: EmailConfig;
  emailAndPassword?: {
    enabled?: boolean;
    requireEmailVerification?: boolean;
    minPasswordLength?: number;
  };
  socialProviders?: Record<string, { clientId: string; clientSecret: string; scopes?: string[] }>;
  social?: SocialConfig;
  onboarding?: OnboardingConfig;
  otp?: OTPConfig;
}

React Hooks

HookReturn highlights
useAuth()isLoaded, isSignedIn, userId, sessionId
useUser()isLoaded, isSignedIn, user, reload
useSession()isLoaded, session
useSignIn()signIn, isLoading, error, fieldErrors
useSignUp()signUp, isLoading, error, fieldErrors
useOAuth()signInWithOAuth
useOTP()step, email, expiresAt, sendCode, verifyCode, reset, isLoading, error
useOnboarding()currentStep, completedSteps, onboardingData, saveStep, completeOnboarding
useUserMetadata()metadata, updateMetadata, getMetadata

Next.js Helpers

const { getSession, getUser, requireAuth } = createServerHelpers(auth);
HelperDescription
getSession()Reads and verifies the session cookie.
getUser()Reads the current user from the adapter.
requireAuth(signInUrl?)Returns the user or redirects.

Adapter Methods

interface BolkAuthAdapter {
  createUser(user): Promise<User>;
  findUserById(id): Promise<User | null>;
  findUserByEmail(email): Promise<User | null>;
  updateUser(id, user): Promise<User>;
  deleteUser(id): Promise<void>;
 
  createSession(session): Promise<Session>;
  findSessionByToken(token): Promise<Session | null>;
  updateSession(id, session): Promise<Session>;
  deleteSession(id): Promise<void>;
  deleteUserSessions(userId): Promise<void>;
 
  createAccount(account): Promise<Account>;
  findAccountByProvider(provider, providerAccountId): Promise<Account | null>;
 
  createVerificationToken(token): Promise<VerificationToken>;
  findVerificationToken(identifier, token): Promise<VerificationToken | null>;
  deleteVerificationToken(identifier, token): Promise<void>;
 
  getUserMetadata(userId, key): Promise<UserMetadata | null>;
  updateUserMetadata(userId, key, value): Promise<UserMetadata>;
}

Previous

Examples

Next

FAQ

On this page

HTTP RoutesConfig ShapeReact HooksNext.js HelpersAdapter Methods