Authentication Endpoints

All authentication endpoints are handled by Better-Auth through a catch-all route at /api/auth/*.

Implementation

From src/app/api/auth/[...all]/route.ts:1-5:

import { auth } from '@/lib/auth'
import { toNextJsHandler } from 'better-auth/next-js'

export const { GET, POST } = toNextJsHandler(auth)

This configuration automatically handles all Better-Auth endpoints.

Base URL

All endpoints are prefixed with /api/auth. The base URL is configured in src/lib/auth/auth.ts:20:

baseURL: getBaseUrl() // Automatically uses NEXT_PUBLIC_APP_URL

Email & Password Endpoints

import { client } from '@/lib/auth'

const result = await client.signUp.email({
  email: 'user@example.com',
  password: 'securePassword123',
  name: 'John Doe'
})

curl -X POST https://yourapp.com/api/auth/sign-up/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "name": "John Doe"
  }'

string

required

User’s email address

string

required

User’s password (minimum requirements defined by Better-Auth)

string

required

User’s display name

object

Created user object

Show properties

string

User ID

string

User email

string

User name

boolean

Email verification status

string | null

Profile image URL

string

Account creation timestamp

object

Session object if auto-signin is enabled

import { client } from '@/lib/auth'

const result = await client.signIn.email({
  email: 'user@example.com',
  password: 'securePassword123'
})

curl -X POST https://yourapp.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123"
  }'

string

required

User’s email address

string

required

User’s password

object

Authenticated user object

object

Created session

Show properties

string

Session ID

string

User ID

string

Session token

string

Session expiration timestamp

Forget Password

import { client } from '@/lib/auth'

await client.forgetPassword({
  email: 'user@example.com',
  redirectTo: '/reset-password'
})

curl -X POST https://yourapp.com/api/auth/forget-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "redirectTo": "/reset-password"
  }'

string

required

Email address to send reset link

string

URL to redirect after clicking reset link

Reset Password

import { client } from '@/lib/auth'

await client.resetPassword({
  newPassword: 'newSecurePassword123',
  token: 'reset_token_from_email'
})

curl -X POST https://yourapp.com/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "newPassword": "newSecurePassword123",
    "token": "reset_token_from_email"
  }'

string

required

New password

string

required

Reset token from email

Email OTP Endpoints

Send OTP

import { client } from '@/lib/auth'

await client.emailOtp.sendVerificationOtp({
  email: 'user@example.com',
  type: 'sign-in'
})

curl -X POST https://yourapp.com/api/auth/email-otp/send \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "type": "sign-in"
  }'

string

required

Email to send OTP code

string

required

OTP type: sign-in, email-verification, or forget-password

Configuration (from src/lib/auth/auth.ts:186-188):

OTP Length: 6 digits
Expiration: 15 minutes
Delivery: Via configured email service

Verify OTP

import { client } from '@/lib/auth'

const result = await client.emailOtp.verifyEmail({
  email: 'user@example.com',
  otp: '123456'
})

curl -X POST https://yourapp.com/api/auth/email-otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "otp": "123456"
  }'

string

required

Email address

string

required

6-digit OTP code from email

object

Authenticated user object

object

Created session

OAuth Endpoints

Initiate OAuth Flow

import { client } from '@/lib/auth'

// Redirects to OAuth provider
await client.signIn.social({
  provider: 'google',
  callbackURL: '/dashboard'
})

# Navigate to:
GET /api/auth/signin/google?callbackURL=/dashboard

string

required

OAuth provider: google, github, microsoft, or facebook

string

URL to redirect after authentication

Supported Providers (from src/lib/auth/auth.ts:45-78):

Google OAuth

Required Environment Variables:

GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET

Scopes: email, profile

GitHub OAuth

Required Environment Variables:

GITHUB_CLIENT_ID
GITHUB_CLIENT_SECRET

Scopes: user:email

Microsoft OAuth

Required Environment Variables:

MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
MICROSOFT_TENANT_ID (optional, defaults to ‘common’)

Facebook OAuth

Required Environment Variables:

FACEBOOK_CLIENT_ID
FACEBOOK_CLIENT_SECRET

Scopes: email, public_profile

OAuth Callback

Better-Auth automatically handles OAuth callbacks at:

GET /api/auth/callback/{provider}

No manual implementation required.

Session Endpoints

Get Session

import { useSession } from '@/lib/auth'

function MyComponent() {
  const { data: session, isPending } = useSession()
  return <div>{session?.user.name}</div>
}

import { auth } from '@/lib/auth'
import { headers } from 'next/headers'

const session = await auth.api.getSession({
  headers: await headers()
})

curl https://yourapp.com/api/auth/get-session \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

object | null

Current session or null if not authenticated

Show properties

object

User object

object

Session metadata

Sign Out

import { signOut } from '@/lib/auth'

await signOut()

curl -X POST https://yourapp.com/api/auth/sign-out \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN"

Organization Endpoints

Create Organization

import { client } from '@/lib/auth'

const { data } = await client.organization.create({
  name: 'Acme Corp',
  slug: 'acme-corp'
})

curl -X POST https://yourapp.com/api/auth/organization/create \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp"
  }'

string

required

Organization name

string

required

URL-friendly slug

object

Created organization

Show properties

string

Organization ID

string

Organization name

string

Organization slug

string

Creation timestamp

Invite Member

import { client } from '@/lib/auth'

await client.organization.inviteMember({
  organizationId: 'org_123',
  email: 'member@example.com',
  role: 'member'
})

curl -X POST https://yourapp.com/api/auth/organization/invite-member \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=YOUR_SESSION_TOKEN" \
  -d '{
    "organizationId": "org_123",
    "email": "member@example.com",
    "role": "member"
  }'

string

required

Organization ID

string

required

Email of person to invite

string

required

Role: member or admin

Error Responses

All endpoints return standard HTTP status codes:

Bad Request

Invalid request parameters or validation error

Unauthorized

Authentication required or invalid credentials

Forbidden

Insufficient permissions

Not Found

Resource not found

Internal Server Error

Server error

Error Response Format:

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

From src/lib/auth/auth.ts:26-33:

advanced: {
  cookiePrefix: APP_COOKIE_NAME, // 'better-auth'
  crossSubDomainCookies: {
    enabled: !isProd,
    domain: '.shipfree.app'
  },
  useSecureCookies: !isProd
}

Authentication

Payments

Database

Authentication Endpoints

Implementation

Base URL

Email & Password Endpoints

Forget Password

Reset Password

Email OTP Endpoints

Send OTP

Verify OTP

OAuth Endpoints

Initiate OAuth Flow

OAuth Callback

Session Endpoints

Get Session

Sign Out

Organization Endpoints

Create Organization

Invite Member

Error Responses

Next Steps

Authentication Overview

Database Schema

​Implementation

​Base URL

​Email & Password Endpoints

​Sign Up

​Sign In

​Forget Password

​Reset Password

​Email OTP Endpoints

​Send OTP

​Verify OTP

​OAuth Endpoints

​Initiate OAuth Flow

​OAuth Callback

​Session Endpoints

​Get Session

​Sign Out

​Organization Endpoints

​Create Organization

​Invite Member

​Error Responses

​Cookie Configuration

​Next Steps

Authentication Overview

Database Schema

Implementation

Base URL

Email & Password Endpoints

Sign Up

Sign In

Forget Password

Reset Password

Email OTP Endpoints

Send OTP

Verify OTP

OAuth Endpoints

Initiate OAuth Flow

OAuth Callback

Session Endpoints

Get Session

Sign Out

Organization Endpoints

Create Organization

Invite Member

Error Responses

Cookie Configuration

Next Steps