Better Auth

https://www.payloadauth.com/docs
Admin
Better Auth is an open-source authentication library that provides email/password, social sign-on,...
Tokens:112,130
Snippets:1,424
Trust Score:4.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run Local Development Commands

Source: https://www.payloadauth.com/docs/contribute/documenting

Commands for installing dependencies and starting the documentation server.

```bash
# Install dependencies
pnpm install
 
# Start docs development server
pnpm -F docs dev
```

--------------------------------

### GET /my-plugin/hello-world

Source: https://www.payloadauth.com/docs/concepts/plugins

An example of a custom GET endpoint created using the createAuthEndpoint utility within a Better Auth plugin.

```APIDOC
## GET /my-plugin/hello-world

### Description
A sample endpoint that returns a 'Hello World' message. This demonstrates the structure of a custom plugin endpoint.

### Method
GET

### Endpoint
/my-plugin/hello-world

### Response
#### Success Response (200)
- **message** (string) - The greeting message returned by the server.

#### Response Example
{
  "message": "Hello World"
}
```

--------------------------------

### Install Stripe Plugin

Source: https://www.payloadauth.com/docs/plugins/stripe

Install the Stripe plugin using npm. If using a separate client and server setup, install in both.

```bash
npm install @better-auth/stripe
```

--------------------------------

### Install Stripe SDK

Source: https://www.payloadauth.com/docs/plugins/stripe

Install the Stripe SDK on your server to interact with the Stripe API.

```bash
npm install stripe
```

--------------------------------

### Install pg package

Source: https://www.payloadauth.com/docs/guides/supabase-migration-guide

Install the 'pg' package to enable database connections.

```bash
npm install pg
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://www.payloadauth.com/docs/contribute/testing

Install project dependencies, including Vitest, and run the test suite.

```bash
pnpm install

pnpm run test
```

--------------------------------

### SSO Plugin Installation

Source: https://www.payloadauth.com/docs/plugins/sso

Steps to install and set up the SSO plugin, including server-side and client-side configurations, and database migrations.

```APIDOC
## Installation

### Add Plugin to the server
```typescript
import { betterAuth } from "better-auth"
import { sso } from "better-auth/plugins/sso";

const auth = betterAuth({
    plugins: [
        sso()
    ]
})
```

### Migrate the database
Run the migration or generate the schema to add the necessary fields and tables to the database.
```bash
npx @better-auth/cli migrate
```

### Add the client plugin
```typescript
import { createAuthClient } from "better-auth/client"
import { ssoClient } from "better-auth/client/plugins"

const authClient = createAuthClient({
    plugins: [
        ssoClient()
    ]
})
```
```

--------------------------------

### Email OTP Plugin Installation

Source: https://www.payloadauth.com/docs/plugins/email-otp

Instructions on how to install and configure the Email OTP plugin in your Better Auth setup.

```APIDOC
## Email OTP Plugin Installation

### Add the plugin to your auth config

To enable email otp in your app, you need to add the `emailOTP` plugin to your auth config.

```typescript
import { betterAuth } from "better-auth"
import { emailOTP } from "better-auth/plugins"
 
export const auth = betterAuth({
    // ... other config options
    plugins: [
        emailOTP({
                async sendVerificationOTP({ email, otp, type}) { 
					// Implement the sendVerificationOTP method to send the OTP to the user's email address
				},
        })
    ]
})
```

### Add the client plugin

```typescript
import { createAuthClient } from "better-auth/client"
import { emailOTPClient } from "better-auth/client/plugins"
 
const authClient =  createAuthClient({
    plugins: [
        emailOTPClient()
    ]
})
```
```

--------------------------------

### Install Polar SDK

Source: https://www.payloadauth.com/docs/plugins/polar

Install the Polar SDK package for server-side integration.

```bash
npm install @polar-sh/sdk
```

--------------------------------

### Multi Session Plugin Installation

Source: https://www.payloadauth.com/docs/plugins/multi-session

Instructions for installing the Multi Session plugin on both the server and client sides.

```APIDOC
## Multi Session Plugin Installation

### Server-side Installation
Add the plugin to your `auth` config.

```typescript
import { betterAuth } from "better-auth"
import { multiSession } from "better-auth/plugins"
 
export const auth = betterAuth({
    plugins: [
        multiSession(),
    ]
})
```

### Client-side Installation
Add the client plugin and specify the redirect URL for 2nd factor verification.

```typescript
import { createAuthClient } from "better-auth/client"
import { multiSessionClient } from "better-auth/client/plugins"
 
const authClient =  createAuthClient({
    plugins: [
        multiSessionClient()
    ]
})
```
```

--------------------------------

### Prepare environment variables

Source: https://www.payloadauth.com/docs/reference/contributing

Creates a local .env file from the provided example.

```bash
cp -n ./docs/.env.example ./docs/.env
```

--------------------------------

### Install Prisma Dependencies

Source: https://www.payloadauth.com/docs/integrations/nitro

Install the Prisma client and CLI tools required for database operations.

```bash
npm install @prisma/client
```

```bash
npm install -D prisma
```

--------------------------------

### Start development servers

Source: https://www.payloadauth.com/docs/reference/contributing

Commands to launch the main development server or the documentation server.

```bash
pnpm dev
```

```bash
pnpm -F docs dev
```

--------------------------------

### Install Better Auth Client

Source: https://www.payloadauth.com/docs/concepts/client

Install the better-auth package using npm. This is the initial step for integrating Better Auth into your project.

```bash
npm i better-auth
```

--------------------------------

### Install Better Auth with npm

Source: https://www.payloadauth.com/docs/installation

Use this command to add Better Auth to your project. If you have a separate client and server setup, install it in both.

```bash
npm install better-auth
```

--------------------------------

### Install dependencies

Source: https://www.payloadauth.com/docs/reference/contributing

Installs project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### Admin Plugin Installation

Source: https://www.payloadauth.com/docs/plugins/admin

Steps to install and configure the Admin plugin for Better Auth.

```APIDOC
## Installation

### Add the plugin to your auth config
To use the Admin plugin, add it to your auth config.
```typescript
import { betterAuth } from "better-auth"
import { admin } from "better-auth/plugins"

export const auth = betterAuth({
    // ... other config options
    plugins: [
        admin()
    ]
})
```

### Migrate the database
Run the migration or generate the schema to add the necessary fields and tables to the database.
```bash
npx @better-auth/cli migrate
```

### Add the client plugin
Next, include the admin client plugin in your authentication client instance.
```typescript
import { createAuthClient } from "better-auth/client"
import { adminClient } from "better-auth/client/plugins"

const authClient = createAuthClient({
    plugins: [
        adminClient()
    ]
})
```
```

--------------------------------

### Start Development Server

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Launch the Plasmo development server.

```bash
pnpm dev
```

--------------------------------

### Example Usage: User Session and Sign Out

Source: https://www.payloadauth.com/docs/integrations/svelte-kit

Demonstrates how to use the auth client to display user session data and provide a sign-out button. This example uses Svelte's reactive stores.

```svelte
<script lang="ts">
  import { authClient } from "$lib/client";
  const session = authClient.useSession();
</script>
    <div>
      {#if $session.data}
        <div>
          <p>
            {$session?.data?.user.name}
          </p>
          <button
            on:click={async () => {
              await authClient.signOut();
            }}
          >
            Sign Out
          </button>
        </div>
      {:else}
        <button
          on:click={async () => {
            await authClient.signIn.social({
              provider: "github",
            });
          }}
        >
          Continue with github
        </button>
      {/if}
    </div>
```

--------------------------------

### Install Bearer Plugin

Source: https://www.payloadauth.com/docs/plugins/bearer

Add the Bearer plugin to your authentication setup by importing and initializing it.

```typescript
import { betterAuth } from "better-auth";
import { bearer } from "better-auth/plugins";

export const auth = betterAuth({
    plugins: [bearer()]
});
```

--------------------------------

### Implement Code Blocks

Source: https://www.payloadauth.com/docs/contribute/documenting

Examples of syntax highlighting, file titles, and line highlighting in MDX.

```typescript
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
});
```

```typescript
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
});
```

```typescript
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({ // [!codeㅤhighlight]
  // configuration  // [!codeㅤhighlight]
}); // [!codeㅤhighlight]
```

```typescript
import { BetterAuth } from "better-auth";
 
const auth = new BetterAuth({
  // configuration
});
```

--------------------------------

### Manage Cookies within a Hook

Source: https://www.payloadauth.com/docs/concepts/hooks

This example shows how to set and get both regular and signed cookies using `ctx.setCookies`, `ctx.setSignedCookie`, `ctx.getCookies`, and `ctx.getSignedCookies`.

```javascript
import { createAuthMiddleware } from "better-auth/api";

const hook = createAuthMiddleware(async (ctx) => {
    ctx.setCookies("my-cookie", "value");
    await ctx.setSignedCookie("my-signed-cookie", "value", ctx.context.secret, {
        maxAge: 1000,
    });

    const cookie = ctx.getCookies("my-cookie");
    const signedCookie = await ctx.getSignedCookies("my-signed-cookie");
});
```

--------------------------------

### Setup Social Providers

Source: https://www.payloadauth.com/docs/guides/supabase-migration-guide

Configure social login providers like GitHub in your better-auth setup, using environment variables for client IDs and secrets.

```typescript
import { admin, anonymous } from "better-auth/plugins";
 
export const auth = betterAuth({
    database: new Pool({
        connectionString: process.env.DATABASE_URL
    }),
    emailAndPassword: {
        enabled: true,
    },
    socialProviders: {
        github: {
            clientId: process.env.GITHUB_CLIENT_ID,
            clientSecret: process.env.GITHUB_CLIENT_SECRET,
        }
    }
})
```

--------------------------------

### Example: Get Session and Role in Layout Server Load

Source: https://www.payloadauth.com/docs/integrations/svelte-kit

Retrieves the user session in a SvelteKit layout server load function. It redirects to login if no session exists and throws a 403 error if the user is not an admin.

```typescript
import type { LayoutServerLoad } from './$types';
import { error, redirect } from '@sveltejs/kit';
import { auth } from '$lib/auth';


export const load: LayoutServerLoad = async ({ request }) => {
    const session = await auth.api.getSession({
          headers: request.headers
    });
    if (!session) {
        console.log('Admin : No session');
        throw redirect(302, '/login');
    }
    if (session.user.role !== 'admin') {
        console.log('Admin : Not admin');
        throw error(403, 'Forbidden');
    }
}; 
```

--------------------------------

### Organization Plugin Configuration

Source: https://www.payloadauth.com/docs/plugins/organization

Example of how to initialize the organization plugin and customize the database schema mapping.

```APIDOC
## Configuration

### Description
Initialize the organization plugin within the Better Auth configuration and customize table or field names.

### Request Example
```typescript
const auth = betterAuth({
  plugins: [organization({
    schema: {
      organization: {
        modelName: "organizations",
        fields: { 
          name: "title"
        }
      }
    }
  })]
})
```
```

--------------------------------

### Email & Password Authentication Setup

Source: https://www.payloadauth.com/docs/basic-usage

Configuration for enabling email and password authentication.

```APIDOC
## Email & Password Authentication Setup

### Description
Configure Better Auth to enable email and password authentication.

### Method
Configuration

### Endpoint
N/A

### Request Body
```json
{
  "emailAndPassword": {
    "enabled": true,
    "autoSignIn": false // defaults to true
  }
}
```

### Response
N/A
```

--------------------------------

### Example: Store Session in Locals and Protect Route

Source: https://www.payloadauth.com/docs/integrations/svelte-kit

This example shows how to store the session and user information in SvelteKit's event locals within the `hooks.server.ts` file. This allows for easier access in subsequent requests.

```typescript
import type { Handle } from '@sveltejs/kit';
import { auth } from '$lib/auth-client';

export const handle: Handle = async ({ event, resolve }) => {
  // Get the session  
  const session = await auth.api.getSession({
    headers: event.request.headers
  });
  // Set session and user to locals 
  event.locals.session = session?.session;
  event.locals.user = session?.user;

  const response = await resolve(event);
  return response;
};  
```

--------------------------------

### Install Better Auth

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Add the Better Auth package to your project dependencies.

```bash
pnpm add better-auth
```

--------------------------------

### Setup Invitation Email

Source: https://www.payloadauth.com/docs/plugins/organization

Configure the `sendInvitationEmail` function for the `better-auth` instance to handle sending invitation emails.

```APIDOC
## Setup Invitation Email

### Description
Configure the `sendInvitationEmail` function for the `better-auth` instance. This function is responsible for sending the invitation email to the user. You'll need to construct and send the invitation link to the user. The link should include the invitation ID, which will be used with the `acceptInvitation` function when the user clicks on it.

### Method
`auth.plugins.organization.sendInvitationEmail` (within `betterAuth` configuration)

### Parameters
#### Request Body (for `sendInvitationEmail` callback)
- **data** (object) - Required - Data object containing invitation details.
  - **data.id** (string) - Required - The unique ID of the invitation.
  - **data.email** (string) - Required - The email address of the invited user.
  - **data.inviter.user.name** (string) - Required - The name of the user sending the invitation.
  - **data.inviter.user.email** (string) - Required - The email of the user sending the invitation.
  - **data.organization.name** (string) - Required - The name of the organization.

### Request Example (Conceptual)
```typescript
import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
import { sendOrganizationInvitation } from "./email"

export const auth = betterAuth({
	plugins: [
		organization({
			async sendInvitationEmail(data) {
                const inviteLink = `https://example.com/accept-invitation/${data.id}`
				sendOrganizationInvitation({
				    email: data.email,
					invitedByUsername: data.inviter.user.name,
					invitedByEmail: data.inviter.user.email,
					teamName: data.organization.name,
					inviteLink
				})
			},
		}),
	],
});
```
```

--------------------------------

### Extend Auth Client with Magic Link Plugin

Source: https://www.payloadauth.com/docs/concepts/client

Initialize the Better Auth client with plugins to add new functionalities. This example demonstrates how to include the magicLinkClient plugin during client creation.

```typescript
import { createAuthClient } from "better-auth/client"
import { magicLinkClient } from "better-auth/client/plugins"

const authClient =  createAuthClient({
    plugins: [
        magicLinkClient()
    ]
})
```

--------------------------------

### Setup Invitation Email Handler

Source: https://www.payloadauth.com/docs/plugins/organization

Configure the sendInvitationEmail callback within the organization plugin to handle email dispatching.

```typescript
import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
import { sendOrganizationInvitation } from "./email"
export const auth = betterAuth({
	plugins: [
		organization({
			async sendInvitationEmail(data) {
                const inviteLink = `https://example.com/accept-invitation/${data.id}`
				sendOrganizationInvitation({
					    email: data.email,
						invitedByUsername: data.inviter.user.name,
						invitedByEmail: data.inviter.user.email,
						teamName: data.organization.name,
						inviteLink
					})
			},
		}),
	],
});
```

--------------------------------

### Configure Trial Periods for Plans

Source: https://www.payloadauth.com/docs/plugins/stripe

Set up trial periods for subscription plans, including custom logic for when a trial starts, ends, or expires without conversion. This allows for automated communication and actions during the trial phase.

```typescript
{
    name: "pro",
    priceId: "price_0987654321",
    freeTrial: {
        days: 14,
        onTrialStart: async (subscription) => {
            // Called when a trial starts
            await sendTrialStartEmail(subscription.referenceId);
        },
        onTrialEnd: async ({ subscription, user }, request) => {
            // Called when a trial ends
            await sendTrialEndEmail(user.email);
        },
        onTrialExpired: async (subscription) => {
            // Called when a trial expires without conversion
            await sendTrialExpiredEmail(subscription.referenceId);
        }
    }
}
```

--------------------------------

### Implement Authorization Logic with Hooks

Source: https://www.payloadauth.com/docs/guides/your-first-plugin

Utilize hooks to run code before or after an action. This example sets up a 'before' hook to intercept requests to the signup path and validate the user's age.

```typescript
import { APIError } from "better-auth/api";
import { createAuthMiddleware } from "better-auth/plugins";

export const birthdayPlugin = () => ({
    //...
    // In our case, we want to write authorization logic,
    // meaning we want to intercept it `before` hand.
    hooks: {
      before: [
        {
          matcher: (context) => context.path.startsWith("/sign-up/email"),
          handler: createAuthMiddleware(async (ctx) => {
            const { birthday } = ctx.body;
            if(!birthday instanceof Date) {
              throw new APIError("BAD_REQUEST", { message: "Birthday must be of type Date." });
            }
 
            const today = new Date();
            const fiveYearsAgo = new Date(today.setFullYear(today.getFullYear() - 5));
 
            if(birthday >= fiveYearsAgo) {
              throw new APIError("BAD_REQUEST", { message: "User must be above 5 years old." });
            }
 
            return { context: ctx };
          }),
        },
      ],
    },
} satisfies BetterAuthPlugin)
```

--------------------------------

### Write tests with Vitest

Source: https://www.payloadauth.com/docs/reference/contributing

Example structure for writing tests using Vitest and the project's test utilities.

```typescript
import { describe, it, expect } from "vitest";
import { getTestInstance } from "./test-utils/test-instance";
 
describe("Feature", () => {
    it("should work as expected", async () => {
        const { client } = getTestInstance();
        // Test code here
        expect(result).toBeDefined();
    });
});
```

--------------------------------

### Initialize Better Auth project with CLI

Source: https://www.payloadauth.com/docs/concepts/cli

Sets up Better Auth in your project with specified configuration options.

```bash
npx @better-auth/cli@latest init
```

--------------------------------

### Initiate OAuth Sign-In

Source: https://www.payloadauth.com/docs/plugins/generic-oauth

Start the OAuth sign-in process by calling the `oauth2` method on the client. Specify the provider ID and the callback URL for redirection after authentication.

```typescript
const response = await authClient.signIn.oauth2({
  providerId: "provider-id",
  callbackURL: "/dashboard" // the path to redirect to after the user is authenticated
});
```

--------------------------------

### Get Session on Server Side (Next.js Example)

Source: https://www.payloadauth.com/docs/basic-usage

Access server-side session data by calling `auth.api.getSession` and passing the request headers. This example demonstrates usage within a Next.js environment.

```typescript
import { auth } from "./auth"; // path to your Better Auth server instance
import { headers } from "next/headers";

const session = await auth.api.getSession({
    headers: await headers() // you need to pass the headers object.
})
```

--------------------------------

### Mount Better Auth handler in TanStack Start

Source: https://www.payloadauth.com/docs/integrations/tanstack

Create an API route file to handle authentication requests via the Better Auth instance.

```typescript
import { auth } from '@/lib/auth'
import { createAPIFileRoute } from '@tanstack/start/api'
 
export const APIRoute = createAPIFileRoute('/api/auth/$')({
  GET: ({ request }) => {
    return auth.handler(request)
  },
  POST: ({ request }) => {
    return auth.handler(request)
  },
})
```

--------------------------------

### Example: Protect Route using Locals in Layout Server Load

Source: https://www.payloadauth.com/docs/integrations/svelte-kit

Demonstrates how to access the session and user from `event.locals` in a SvelteKit layout server load function to protect routes. It redirects or throws an error based on session and user role.

```typescript
import type { LayoutServerLoad } from './$types';
import { error, redirect } from '@sveltejs/kit';

export const load: LayoutServerLoad = async ({ locals }) => {
    const session = locals.session;
    const user = locals.user;

    if (!session) {
        console.log('Admin : No session');
        throw redirect(302, '/login');
    }
    if (user?.role !== 'admin') {
        console.log('Admin : Not admin');
        throw error(403, 'Forbidden');
    }
}; 
```

--------------------------------

### Initialize Prisma

Source: https://www.payloadauth.com/docs/integrations/nitro

Generate the initial Prisma configuration files.

```bash
npx prisma init
```

--------------------------------

### Create Migration File

Source: https://www.payloadauth.com/docs/guides/supabase-migration-guide

Initialize the migration file using the terminal.

```bash
touch migration.ts
```

--------------------------------

### Install CORS Package

Source: https://www.payloadauth.com/docs/integrations/nitro

Install the cors middleware package.

```bash
npm install cors
```

--------------------------------

### Client-Side Configuration

Source: https://www.payloadauth.com/docs/plugins/2fa

How to initialize the two-factor authentication client plugin.

```APIDOC
## Client Configuration

### Description
Initialize the two-factor authentication client plugin within the Better Auth client configuration.

### Request Example
```typescript
import { createAuthClient } from "better-auth/client"
import { twoFactorClient } from "better-auth/client/plugins"
 
const authClient =  createAuthClient({
    plugins: [
        twoFactorClient({ 
            onTwoFactorRedirect(){
                window.location.href = "/2fa"
            }
        }) 
    ]
})
```
```

--------------------------------

### Install Polar Better Auth Plugin

Source: https://www.payloadauth.com/docs/plugins/polar

Install the required npm package for the Polar Better Auth plugin.

```bash
npm install @polar-sh/better-auth
```

--------------------------------

### Bundle Extension

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Generate a production build of the extension.

```bash
pnpm build
```

--------------------------------

### Install Better Auth Expo Package

Source: https://www.payloadauth.com/docs/integrations/expo

Install the Better Auth Expo package in your Expo app using npm. This package provides necessary integrations for Expo.

```bash
npm install @better-auth/expo
```

--------------------------------

### Clone the repository

Source: https://www.payloadauth.com/docs/reference/contributing

Initializes the local development environment by cloning the forked repository.

```bash
# Replace YOUR-USERNAME with your GitHub username
git clone https://github.com/YOUR-USERNAME/better-auth.git
cd better-auth
```

--------------------------------

### Prisma Schema Mapping Example

Source: https://www.payloadauth.com/docs/guides/next-auth-migration-guide

Example of how to map session schema fields in Prisma using the @map annotation to align with Better Auth's expected schema.

```prisma
model Session {
    id          String   @id @default(cuid())
    expires     DateTime @map("expiresAt") // Map `expires` to your existing field
    token       String   @map("sessionToken") // Map `token` to your existing field
    userId      String
    user        User     @relation(fields: [userId], references: [id])
}
```

--------------------------------

### Create Client Auth Instance

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Initialize the Better Auth client instance in your project.

```typescript
import { createAuthClient } from "better-auth/react"
 
export const authClient = createAuthClient({
    baseURL: "http://localhost:3000" /* base url of your Better Auth backend. */,
    plugins: [],
});
```

--------------------------------

### GET /organization/listTeams

Source: https://www.payloadauth.com/docs/plugins/organization

Retrieves a list of all teams within an organization.

```APIDOC
## GET /organization/listTeams

### Description
Retrieves all teams associated with an organization.

### Method
GET

### Query Parameters
- **organizationId** (string) - Optional - The ID of the organization, defaults to active organization
```

--------------------------------

### Initialize Plasmo Project

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Create a new Plasmo project with TailwindCSS and a src directory.

```bash
pnpm create plasmo --with-tailwindcss --with-src
```

--------------------------------

### GET /api/getApiKey

Source: https://www.payloadauth.com/docs/plugins/api-key

Retrieves an existing API key by its ID.

```APIDOC
## GET /api/getApiKey

### Description
Retrieves details of a specific API key, including its associated metadata.

### Method
GET

### Endpoint
/api/getApiKey

### Request Body
- **keyId** (string) - Required - The unique identifier of the API key.

### Request Example
{
  "keyId": "your_api_key_id_here"
}

### Response
#### Success Response (200)
- **metadata** (object) - The metadata object associated with the key.
```

--------------------------------

### Execute Migration Script

Source: https://www.payloadauth.com/docs/guides/supabase-migration-guide

Run the migration script using a runtime like bun, node, or ts-node.

```bash
bun migration.ts # or use node, ts-node, etc.
```

--------------------------------

### GET /api/organization/getActiveMember

Source: https://www.payloadauth.com/docs/plugins/organization

Retrieve details of the currently active member in the organization.

```APIDOC
## GET /api/organization/getActiveMember

### Description
Retrieve information about the currently active member within the organization context.

### Method
GET

### Endpoint
`/api/organization/getActiveMember`

### Response
#### Success Response (200)
- **member** (object) - Details of the active member.
  - **id** (string) - The member's ID.
  - **userId** (string) - The user's ID.
  - **organizationId** (string) - The organization's ID.
  - **role** (string | string[]) - The member's role(s).

#### Response Example
```json
{
  "member": {
    "id": "member-id",
    "userId": "user-id",
    "organizationId": "org-id",
    "role": "admin"
  }
}
```
```

--------------------------------

### Initialize Better Auth Client

Source: https://www.payloadauth.com/docs/installation

Create a client instance by importing createAuthClient and specifying the base URL of your authentication server.

```typescript
import { createAuthClient } from "better-auth/react"
export const authClient = createAuthClient({
    /** the base url of the server (optional if you're using the same domain) */
    baseURL: "http://localhost:3000"
})
```

--------------------------------

### GET /api/organization/getInvitation

Source: https://www.payloadauth.com/docs/plugins/organization

Retrieve details of a specific invitation using its ID.

```APIDOC
## GET /api/organization/getInvitation

### Description
Retrieve details for a specific invitation.

### Method
GET

### Endpoint
`/api/organization/getInvitation`

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the invitation to retrieve.

### Request Example
```bash
GET /api/organization/getInvitation?id=invitation-id
```

### Response
#### Success Response (200)
- **invitation** (object) - Details of the invitation.
  - **id** (string) - The invitation ID.
  - **email** (string) - The email address of the invitee.
  - **role** (string | string[]) - The role(s) assigned.
  - **organizationId** (string) - The ID of the organization.
  - **status** (string) - The current status of the invitation (e.g., 'pending', 'accepted', 'rejected', 'cancelled').

#### Response Example
```json
{
  "invitation": {
    "id": "invitation-id",
    "email": "invitee@example.com",
    "role": "member",
    "organizationId": "org-id",
    "status": "pending"
  }
}
```
```

--------------------------------

### Implement Sign Up Route

Source: https://www.payloadauth.com/docs/integrations/remix

Use the auth client to handle user registration via email and password within a Remix form.

```typescript
import { Form } from "@remix-run/react"
import { useState } from "react"
import { authClient } from "~/lib/auth.client"
 
export default function SignUp() {
  const [email, setEmail] = useState("")
  const [name, setName] = useState("")
  const [password, setPassword] = useState("")
 
  const signUp = async () => {
    await authClient.signUp.email(
      {
        email,
        password,
        name,
      },
      {
        onRequest: (ctx) => {
          // show loading state
        },
        onSuccess: (ctx) => {
          // redirect to home
        },
        onError: (ctx) => {
          alert(ctx.error)
        },
      },
    )
  }
 
  return (
    <div>
      <h2>
        Sign Up
      </h2>
      <Form
        onSubmit={signUp}
      >
        <input
          type="text"
          value={name}
          onChange={(e) => setName(e.target.value)}
          placeholder="Name"
        />
        <input
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          placeholder="Email"
        />
        <input
          type="password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          placeholder="Password"
        />
        <button
          type="submit"
        >
          Sign Up
        </button>
      </Form>
    </div>
  )
}
```

--------------------------------

### GET /api-key/get

Source: https://www.payloadauth.com/docs/plugins/api-key

Retrieves details for a specific API key by its ID.

```APIDOC
## GET /api-key/get

### Description
Fetches information about an API key using its ID.

### Method
GET

### Endpoint
/api-key/get

### Parameters
#### Request Body
- **keyId** (string) - Required - The ID of the API key.

### Response
#### Success Response (200)
- **ApiKey** (object) - API key details excluding the secret key value.
```

--------------------------------

### Get Full Organization Details

Source: https://www.payloadauth.com/docs/plugins/organization

Retrieves comprehensive details for a specific organization.

```APIDOC
## GET /organization/getFullOrganization

### Description
Fetches full details of an organization. Defaults to the active organization if no ID or slug is provided.

### Method
GET

### Parameters
#### Query Parameters
- **organizationId** (string) - Optional - The ID of the organization.
- **organizationSlug** (string) - Optional - The slug of the organization.

### Request Example
{
  "organizationId": "organization-id"
}
```

--------------------------------

### GET /oauth2/userinfo

Source: https://www.payloadauth.com/docs/plugins/oidc-provider

Retrieves information about the authenticated user based on granted scopes.

```APIDOC
## GET /oauth2/userinfo

### Description
Retrieves user details for an authenticated session. Requires a valid access token in the Authorization header.

### Method
GET

### Endpoint
/oauth2/userinfo

### Parameters
#### Request Headers
- **Authorization** (string) - Required - Bearer ACCESS_TOKEN

### Response
#### Success Response (200)
- **sub** (string) - User ID (returned with openid scope)
- **name** (string) - User name (returned with profile scope)
- **picture** (string) - User profile picture (returned with profile scope)
- **email** (string) - User email (returned with email scope)
- **email_verified** (boolean) - Email verification status (returned with email scope)
```

--------------------------------

### Configure Client-Side Plugins

Source: https://www.payloadauth.com/docs/concepts/plugins

Initialize client-side plugins by passing them to the plugins array in the createAuthClient function.

```typescript
import { createAuthClient } from "better-auth/client";
 
const authClient =  createAuthClient({
    plugins: [
        // Add your client plugins here
    ]
});
```

--------------------------------

### GET /magicLink/verify

Source: https://www.payloadauth.com/docs/plugins/magic-link

Verifies the magic link token to authenticate the user session.

```APIDOC
## GET /magicLink/verify

### Description
Verifies the token provided in the magic link to complete the authentication process.

### Method
GET

### Parameters
#### Query Parameters
- **token** (string) - Required - The unique token generated for the magic link.

### Request Example
{
  "query": {
    "token": "example-token-string"
  }
}
```

--------------------------------

### Initialize Admin Client Plugin

Source: https://www.payloadauth.com/docs/plugins/admin

Include the admin client plugin in the authentication client instance.

```typescript
import { createAuthClient } from "better-auth/client"
import { adminClient } from "better-auth/client/plugins"
 
const authClient = createAuthClient({
    plugins: [
        adminClient()
    ]
})
```

--------------------------------

### Configure Client Plugin

Source: https://www.payloadauth.com/docs/plugins/one-tap

Initialize the client-side plugin with your Google Client ID and optional prompt behavior settings.

```typescript
import { createAuthClient } from "better-auth/client";
import { oneTapClient } from "better-auth/client/plugins";
 
const authClient = createAuthClient({
  plugins: [
    oneTapClient({
      clientId: "YOUR_CLIENT_ID",
      // Optional client configuration:
      autoSelect: false,
      cancelOnTapOutside: true,
      context: "signin",
      additionalOptions: {
        // Any extra options for the Google initialize method
      },
      // Configure prompt behavior and exponential backoff:
      promptOptions: {
        baseDelay: 1000,   // Base delay in ms (default: 1000)
        maxAttempts: 5     // Maximum number of attempts before triggering onPromptNotification (default: 5)
      }
    })
  ]
});
```

--------------------------------

### Initialize Better Auth Client

Source: https://www.payloadauth.com/docs/integrations/remix

Create a client-side instance using the react-specific entry point to enable authentication hooks and methods.

```typescript
import { createAuthClient } from "better-auth/react" // make sure to import from better-auth/react
 
export const authClient = createAuthClient({
    //you can pass client configuration here
})
```

--------------------------------

### GET /client/subscription/list

Source: https://www.payloadauth.com/docs/plugins/stripe

Retrieves a list of the user's or organization's active and trialing subscriptions.

```APIDOC
## GET /client/subscription/list

### Description
Fetches all active and trialing subscriptions associated with the current user or a specified reference ID.

### Method
GET

### Endpoint
`/client/subscription/list`

### Parameters
#### Query Parameters
- **referenceId** (string) - Optional - The ID of the organization or entity to list subscriptions for. Defaults to the current user ID.

### Response
#### Success Response (200)
- **data** (array) - An array of subscription objects.
  - **status** (string) - The current status of the subscription (e.g., "active", "trialing").
  - **limits** (object) - The limits associated with the subscription (e.g., `projects`, `storage`).

### Response Example
```json
{
  "data": [
    {
      "status": "active",
      "limits": {
        "projects": 20,
        "storage": 50
      }
    }
  ]
}
```
```

--------------------------------

### Generate Database Schema for Plugins

Source: https://www.payloadauth.com/docs/basic-usage

Run the `npx @better-auth/cli generate` command to create the necessary database schema for plugins like two-factor authentication.

```bash
npx @better-auth/cli generate
```

--------------------------------

### Email OTP Usage

Source: https://www.payloadauth.com/docs/plugins/email-otp

Examples of how to use the Email OTP plugin for various authentication flows.

```APIDOC
## Usage

### Send OTP

First, send an OTP to the user's email address.

```typescript
const { data, error } = await authClient.emailOtp.sendVerificationOtp({
    email: "user-email@email.com",
    type: "sign-in" // or "email-verification", "forget-password"
})
```

### SignIn with OTP

Once the user provides the OTP, you can sign in the user using the `signIn.emailOTP()` method.

```typescript
const { data, error } = await authClient.signIn.emailOtp({
    email: "user-email@email.com",
    otp: "123456"
})
```

If the user is not registered, they'll be automatically registered. If you want to prevent this, you can pass `disableSignUp` as `true` in the options.

### Verify Email

To verify the user's email address, use the `verifyEmail()` method.

```typescript
const { data, error } = await authClient.emailOtp.verifyEmail({
    email: "user-email@email.com",
    otp: "123456"
})
```

### Reset Password

To reset the user's password, use the `resetPassword()` method.

```typescript
const { data, error } = await authClient.emailOtp.resetPassword({
    email: "user-email@email.com",
    otp: "123456",
    password: "password"
})
```
```

--------------------------------

### Implement Popup Authentication

Source: https://www.payloadauth.com/docs/guides/browser-extension-guide

Example of using the auth client within a React popup component.

```typescript
import { authClient } from "./auth/auth-client"
 
 
function IndexPopup() {
    const {data, isPending, error} = authClient.useSession();
    if(isPending){
        return <>Loading...</>
    }
    if(error){
        return <>Error: {error.message}</>
    }
    if(data){
        return <>Signed in as {data.user.name}</>
    }
}
 
export default IndexPopup;
```

--------------------------------

### Create the auth client

Source: https://www.payloadauth.com/docs/integrations/astro

Initialize the Better Auth client for use in frontend frameworks or vanilla JavaScript.

```typescript
import { createAuthClient } from "better-auth/client"
export const authClient =  createAuthClient()
```

--------------------------------

### Initialize Better Auth Client

Source: https://www.payloadauth.com/docs/integrations/next

Create a client instance for interacting with auth actions on the frontend.

```typescript
import { createAuthClient } from "better-auth/react" // make sure to import from better-auth/react
 
export const authClient =  createAuthClient({
    //you can pass client configuration here
})
```

--------------------------------

### Get Active Member

Source: https://www.payloadauth.com/docs/plugins/organization

Retrieve the current user's member profile within the active organization.

```typescript
const member = await authClient.organization.getActiveMember()
```

--------------------------------

### Set Database URL

Source: https://www.payloadauth.com/docs/integrations/nitro

Define the database connection string in the environment configuration.

```bash
DATABASE_URL="file:./dev.db"
```

--------------------------------

### GET /api/admin/users - List Users

Source: https://www.payloadauth.com/docs/plugins/admin

Allows an admin to list all users in the database with filtering and pagination options.

```APIDOC
## GET /api/admin/users - List Users

### Description
Allows an admin to list all users in the database. Supports filtering, searching, sorting, and pagination.

### Method
GET

### Endpoint
/api/admin/users

### Query Parameters
- **search** (object) - Optional - Search criteria for users.
  - **field** (string) - Required - The field to search on (`email` or `name`).
  - **operator** (string) - Required - The operator to use for the search (`contains`, `starts_with`, `ends_with`).
  - **value** (string) - Required - The value to search for.
- **limit** (number) - Optional - The maximum number of users to return. Defaults to 100.
- **offset** (number) - Optional - The number of users to skip for pagination. Defaults to 0.
- **sortBy** (string) - Optional - The field to sort the users by (e.g., `createdAt`).
- **sortDirection** (string) - Optional - The direction to sort the users by (`asc` or `desc`). Defaults to `asc`.
- **filter** (array of objects) - Optional - An array of filter objects to apply.
  - **field** (string) - Required - The field to filter on (e.g., `role`).
  - **operator** (string) - Required - The operator to use for filtering (e.g., `eq`).
  - **value** (any) - Required - The value to filter by.

### Request Example (with search, limit, offset, sort, and filter)
```json
{
  "query": {
    "searchField": "email",
    "searchOperator": "contains",
    "searchValue": "@example.com",
    "limit": 10,
    "offset": 0,
    "sortBy": "createdAt",
    "sortDirection": "desc",
    "filterField": "role",
    "filterOperator": "eq",
    "filterValue": "admin"
  }
}
```

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
- **total** (number) - The total number of users matching the query after filters and search.
- **limit** (number | undefined) - The limit provided in the query.
- **offset** (number | undefined) - The offset provided in the query.

#### Response Example
```json
{
  "users": [
    {
      "id": "user_id_1",
      "name": "Admin User",
      "email": "admin@example.com",
      "role": "admin",
      "createdAt": "2023-10-26T10:00:00Z",
      "updatedAt": "2023-10-26T10:00:00Z"
    }
    // ... more users
  ],
  "total": 50,
  "limit": 10,
  "offset": 0
}
```

### Pagination Implementation Details
- **Total pages:** `Math.ceil(total / limit)`
- **Current page:** `(offset / limit) + 1`
- **Next page offset:** `Math.min(offset + limit, (total - 1))`
- **Previous page offset:** `Math.max(0, offset - limit)`

#### Example Usage for Pagination
```typescript
const pageSize = 10;
const currentPage = 2;

const users = await authClient.admin.listUsers({
    query: {
        limit: pageSize,
        offset: (currentPage - 1) * pageSize
    }
});

const totalUsers = users.total;
const totalPages = Math.ceil(totalUsers / limit);
```
```

--------------------------------

### GET /oauth2/callback/:providerId

Source: https://www.payloadauth.com/docs/plugins/generic-oauth

The callback endpoint used by OAuth providers to return the authorization code to the application.

```APIDOC
## GET /oauth2/callback/:providerId

### Description
This endpoint is automatically mounted by the plugin to handle the OAuth callback process. It processes the authorization code returned by the provider to complete the authentication flow.

### Method
GET

### Endpoint
/api/auth/oauth2/callback/:providerId

### Parameters
#### Path Parameters
- **providerId** (string) - Required - The unique identifier for the OAuth provider configured in the plugin.
```

--------------------------------

### Initialize Better Auth

Source: https://www.payloadauth.com/docs/integrations/nitro

Create the Better Auth instance using the Prisma adapter.

```typescript
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { PrismaClient } from "@prisma/client";
 
const prisma = new PrismaClient();
export const auth = betterAuth({
  database: prismaAdapter(prisma, { provider: "sqlite" }),
  emailAndPassword: { enabled: true },
});
```

--------------------------------

### Retrieve JWT Token

Source: https://www.payloadauth.com/docs/plugins/jwt

Examples for obtaining the JWT token via API response or session headers.

```json
  { 
    "token": "ey..."
  }
```

```javascript
await fetch("/api/auth/token", {
  headers: {
    "Authorization": `Bearer ${token}`
  },
})
```

```javascript
await authClient.getSession({
  fetchOptions: {
    onSuccess: (ctx)=>{
      const jwt = ctx.response.headers.get("set-auth-jwt")
    }
  }
})
```

--------------------------------

### Initialize Organization Client

Source: https://www.payloadauth.com/docs/plugins/organization

Add the organization client plugin to your Better Auth client configuration.

```typescript
import { createAuthClient } from "better-auth/client"
import { organizationClient } from "better-auth/client/plugins"
 
const client = createAuthClient({
    plugins: [ 
        organizationClient() 
    ] 
})
```

--------------------------------

### Configure Social Sign-On Provider (GitHub)

Source: https://www.payloadauth.com/docs/basic-usage

Set up social providers by configuring the `socialProviders` option in your `auth` object. Ensure you provide the necessary `clientId` and `clientSecret` from your provider's application settings.

```typescript
import { betterAuth } from "better-auth";

export const auth = betterAuth({
    socialProviders: {
        github: {
            clientId: process.env.GITHUB_CLIENT_ID!,
            clientSecret: process.env.GITHUB_CLIENT_SECRET!,
        }
    },
})
```

--------------------------------

### User Deletion Configuration and Callbacks

Source: https://www.payloadauth.com/docs/concepts/users-accounts

Configuration options for the deleteUser feature, including email verification setup and lifecycle hooks.

```APIDOC
## User Deletion Configuration

### Description
Configure the deleteUser behavior within the betterAuth initialization, including email verification logic and lifecycle callbacks.

### Configuration Fields
- **enabled** (boolean) - Required - Enables the delete user functionality.
- **sendDeleteAccountVerification** (function) - Optional - Callback to send a verification email with a token and URL.
- **beforeDelete** (function) - Optional - Hook executed before deletion; can throw APIError to abort.
- **afterDelete** (function) - Optional - Hook executed after successful deletion.
```

--------------------------------

### Configure Better Auth with Prisma Adapter

Source: https://www.payloadauth.com/docs/adapters/prisma

Initialize the Better Auth instance using the Prisma adapter with a specified database provider.

```typescript
import { betterAuth } from "better-auth";
import { prismaAdapter } from "better-auth/adapters/prisma";
import { PrismaClient } from "@prisma/client";
 
const prisma = new PrismaClient();
 
export const auth = betterAuth({
  database: prismaAdapter(prisma, {
    provider: "sqlite",
  }),
});
```

--------------------------------

### Configure Google OAuth Provider

Source: https://www.payloadauth.com/docs/concepts/oauth

Basic setup for a social provider using client credentials within the betterAuth configuration.

```typescript
import { betterAuth } from 'better-auth';
 
export const auth = betterAuth({
    // Other configurations...
    socialProviders: {
        google: {
            clientId: 'YOUR_GOOGLE_CLIENT_ID',
            clientSecret: 'YOUR_GOOGLE_CLIENT_SECRET',
        }
    }
})
```

--------------------------------

### Create Better Auth Client

Source: https://www.payloadauth.com/docs/integrations/svelte-kit

Create a client instance for authentication actions. This client uses nano-store for state management, reflecting changes like user sign-in/out.

```typescript
import { createAuthClient } from "better-auth/svelte" // make sure to import from better-auth/svelte

export const authClient = createAuthClient({
    // you can pass client configuration here
})
```

--------------------------------

### Initialize Email OTP Client Plugin

Source: https://www.payloadauth.com/docs/plugins/email-otp

Add the `emailOTPClient` plugin to your auth client configuration to enable email OTP features on the client-side.

```typescript
import { createAuthClient } from "better-auth/client"
import { emailOTPClient } from "better-auth/client/plugins"

const authClient =  createAuthClient({
    plugins: [
        emailOTPClient()
    ]
})
```

--------------------------------

### Customizing User Mapping

Source: https://www.payloadauth.com/docs/concepts/oauth

Example of using `mapProfileToUser` to customize how provider profile information is mapped to your internal user object.

```APIDOC
## Customizing User Mapping

### Example using `mapProfileToUser`

```typescript
import { betterAuth } from 'better-auth';

export const auth = betterAuth({
    // Other configurations...
    socialProviders: {
        google: {
            clientId: 'YOUR_GOOGLE_CLIENT_ID',
            clientSecret: 'YOUR_GOOGLE_CLIENT_SECRET',
            mapProfileToUser: (profile) => {
                return {
                   firstName: profile.given_name,
                   lastName: profile.family_name,
                }
            }
        }
    }
})
```
```

--------------------------------

### Trial Periods Configuration

Source: https://www.payloadauth.com/docs/plugins/stripe

Allows configuration of trial periods for subscription plans, including start, end, and expiration hooks.

```APIDOC
## Trial Periods

### Description
Configure trial periods for your subscription plans, including custom logic for when a trial starts, ends, or expires.

### Configuration Example

```typescript
{
    name: "pro",
    priceId: "price_0987654321",
    freeTrial: {
        days: 14,
        onTrialStart: async (subscription) => {
            // Called when a trial starts
            await sendTrialStartEmail(subscription.referenceId);
        },
        onTrialEnd: async ({ subscription, user }, request) => {
            // Called when a trial ends
            await sendTrialEndEmail(user.email);
        },
        onTrialExpired: async (subscription) => {
            // Called when a trial expires without conversion
            await sendTrialExpiredEmail(subscription.referenceId);
        }
    }
}
```
```

--------------------------------

### Add Username Plugin to Server

Source: https://www.payloadauth.com/docs/plugins/username

Integrate the username plugin into your Better Auth server configuration. Ensure 'better-auth' and its plugins are installed.

```typescript
import { betterAuth } from "better-auth"
import { username } from "better-auth/plugins"

const auth = betterAuth({
    plugins: [
        username() 
    ] 
})
```

--------------------------------

### Sign Up User with Username

Source: https://www.payloadauth.com/docs/plugins/username

Use the `signUp.email` function with the additional `username` property to register a new user. Ensure the client is configured with the username plugin.

```typescript
const data = await authClient.signUp.email({
    email: "email@domain.com",
    name: "Test User",
    password: "password1234",
    username: "test"
})
```
Tokens:
Raw