internal_server_error definition
The internal_server_error occurs when an unexpected failure happens inside the authentication process.
Better Auth · Plugins · all subjects
out of scope
40 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Troubleshooting internal_server_error
To fix an internal_server_error: check server logs for detailed error information, verify database connectivity and configuration, ensure all required environment variables are set correctly, and review any custom hooks or adapters for runtime errors.
Dub plugin installation and setup
Install the Dub Better Auth plugin using @dub/better-auth and the Dub SDK using the dub package. Configure the plugin by importing dubAnalytics from @dub/better-auth, creating a new Dub() instance, and adding dubAnalytics({ dubClient: new Dub() }) to the plugins array in betterAuth configuration.
Dub plugin lead tracking default behavior
By default, the Dub plugin tracks sign up events as leads. Lead tracking can be disabled by setting disableLeadTracking to true in the plugin configuration.
Dub plugin OAuth configuration options
The Dub plugin supports OAuth configuration with the following options: clientId (Client ID for Dub OAuth), clientSecret (Client secret for Dub OAuth), and pkce (enable PKCE for Dub OAuth).
Dub plugin configuration parameters
The Dub plugin accepts these configuration parameters: dubClient (required, Dub client instance), disableLeadTracking (disable lead tracking for sign up events), leadEventName (event name for sign up leads), customLeadTrack (custom lead track function), and oauth (Dub OAuth configuration object).
Dub plugin client-side usage
On the client side, import dubAnalyticsClient from @dub/better-auth/client and add dubAnalyticsClient() to the plugins array in createAuthClient configuration to enable Dub account linking.
Dub OAuth account linking endpoint
To link an account with Dub, use the POST /dub/link endpoint. This endpoint requires an active session and accepts a callbackURL parameter (optional, defaults to /dashboard) that specifies the URL to redirect to after linking.
Dub plugin functionality overview
The Dub plugin provides two main features: lead tracking that monitors when users sign up using a Dub link, and OAuth linking support that allows building integrations extending Dub's linking management infrastructure.
Open API plugin installation
To add the Open API plugin to Better Auth, import it from 'better-auth/plugins' and add it to the plugins array in the betterAuth config using openAPI().
Open API reference URL endpoint
The Open API reference is served at /api/auth/reference by default after installing the plugin. Navigate to this URL to view the Open API reference UI.
Open API endpoints grouped by plugin
In the Open API reference, each plugin's endpoints are grouped by the plugin name. Core endpoints are grouped under the 'Default' group. Model schemas are grouped under the 'Models' group.
Generate Open API schema as JSON
To retrieve the generated Open API schema as a JSON object, call auth.api.generateOpenAPISchema(). This returns the complete Open API schema.
Open API specification version
The Open API reference is generated using the OpenAPI 3.1.1 specification. Client generators and tooling used with the schema should support OpenAPI 3.1 semantics.
Scalar integration for multiple API sources
When using Scalar for OpenAPI documentation, you can integrate Better Auth as an additional source by adding a source entry with the URL /api/auth/open-api/generate-schema alongside your main API sources.
Open API plugin configuration options
The Open API plugin accepts the following configuration options: path (string, default '/api/auth/reference') - the path where the Open API reference is served; disableDefaultReference (boolean, default false) - disable the default Scalar UI if set to true; theme (string, default 'default') - change the theme of the OpenAPI reference page; nonce (string, default undefined) - pass a nonce string for Content Security Policy (CSP) compliance.
Open API reference UI library
The Open API plugin uses the Scalar library to display the OpenAPI reference. Scalar provides interactive documentation with a 'Try it out' button for testing endpoints with parameters.
Polar plugin installation
Install the Polar plugin with: pnpm add better-auth @polar-sh/better-auth @polar-sh/sdk
Polar plugin features overview
The Polar plugin provides: Checkout Integration, Customer Portal, Automatic Customer creation on signup, Event Ingestion & Customer Meters for flexible Usage Based Billing, Handle Polar Webhooks securely with signature verification, and Reference System to associate purchases with organizations.
Polar plugin server-side configuration
The Polar plugin is configured on the server-side with betterAuth(). Import and include the polar() plugin with a Polar SDK client instance. Sub-plugins are included via the use array: checkout, portal, usage, and webhooks.
Polar plugin client-side configuration
The Polar plugin is configured on the client-side using createAuthClient() with the polarClient() plugin. All Polar plugins and functionality are attached to the server-side BetterAuth config only.
Polar plugin required options
The required option for the polar() plugin is: client (Polar SDK client instance).
Polar plugin optional options
Optional options for the polar() plugin are: createCustomerOnSignUp (boolean, automatically create a Polar customer when a user signs up) and getCustomerCreateParams (function to provide additional customer creation metadata).
Polar customer auto-creation
When createCustomerOnSignUp is enabled, a new Polar Customer is automatically created when a new User is added to the Better-Auth Database. All new customers are created with an associated externalId which is the ID of the User in the Database.
Checkout plugin configuration options
Checkout plugin options are: products (optional, array of objects with productId and slug fields to map Product IDs to custom slugs), successUrl (relative URL to return to when checkout is successfully completed, supports {CHECKOUT_ID} placeholder), and authenticatedUsersOnly (boolean, whether to allow only authenticated checkouts).
Checkout plugin client method
On the client, use authClient.checkout() to initialize Checkout Sessions. Pass either products array with Polar Product IDs or slug if products are configured. Optionally pass referenceId to associate the checkout with an organization.
Checkout with organization reference
The checkout plugin supports organization references. Pass organizationId as referenceId in the authClient.checkout() call. The Reference ID will be saved as referenceId in the metadata of the checkout, order & subscription object.
Portal plugin functionality
The portal plugin enables customer management of purchases, orders, and subscriptions. It adds customer management methods to authClient.customer.
Portal plugin redirect method
The portal plugin provides authClient.customer.portal() method which redirects the user to the Polar Customer Portal where they can see orders, purchases, subscriptions, and benefits.
Portal plugin customer state method
The portal plugin provides authClient.customer.state() method which returns the general Customer State object containing all customer data, active subscriptions, granted benefits, and active meters with their current balance.
Portal plugin benefits list method
The portal plugin provides authClient.customer.benefits.list() with query parameters page and limit to list granted benefits for the authenticated user/customer.
Portal plugin orders list method
The portal plugin provides authClient.customer.orders.list() with query parameters page, limit, and productBillingType (one_time or recurring) to list orders for the authenticated user/customer.
Portal plugin subscriptions list method
The portal plugin provides authClient.customer.subscriptions.list() with query parameters page, limit, active, and optionally referenceId to list subscriptions for the authenticated user/customer or associated with a referenceId.
Portal plugin organization subscriptions
The portal plugin subscriptions list method does not return subscriptions made by a parent organization to the authenticated user. Pass referenceId (organization ID) to return all subscriptions associated with that organization instead.
Usage plugin event ingestion
The usage plugin provides authClient.usage.ingest() method to ingest events for Usage Based Billing. Pass event name and optional metadata. The authenticated user is automatically associated with the ingested event.
Usage plugin customer meters list method
The usage plugin provides authClient.usage.meters.list() with query parameters page and limit to list the authenticated user's Customer Meters containing consumption information on defined meters.
Webhooks plugin configuration
The webhooks plugin is configured with required secret option (POLAR_WEBHOOK_SECRET from environment) and optional handler functions for webhook events.
Webhooks plugin endpoint
The Polar webhooks endpoint is configured at /polar/webhooks. Configure this endpoint in Polar Organization Settings page.
Webhooks plugin handlers list
The webhooks plugin supports 26 handlers: onPayload (catch-all), onCheckoutCreated, onCheckoutUpdated, onOrderCreated, onOrderPaid, onOrderRefunded, onRefundCreated, onRefundUpdated, onSubscriptionCreated, onSubscriptionUpdated, onSubscriptionActive, onSubscriptionCanceled, onSubscriptionRevoked, onSubscriptionUncanceled, onProductCreated, onProductUpdated, onOrganizationUpdated, onBenefitCreated, onBenefitUpdated, onBenefitGrantCreated, onBenefitGrantUpdated, onBenefitGrantRevoked, onCustomerCreated, onCustomerUpdated, onCustomerDeleted, and onCustomerStateChanged.
Polar plugin environment setup
Set up environment variables: POLAR_ACCESS_TOKEN (required, Polar Organization Access Token) and POLAR_WEBHOOK_SECRET (required for webhooks). Polar SDK client accepts server option set to 'sandbox' for sandbox environment or 'production' for production.