Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/revokslab/shipfree/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Sign Up

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

const result = await client.signUp.email({
  email: 'user@example.com',
  password: 'securePassword123',
  name: 'John Doe'
})
​
email
string
required
User’s email address
​
password
string
required
User’s password (minimum requirements defined by Better-Auth)
​
name
string
required
User’s display name
​
user
object
Created user object
​
session
object
Session object if auto-signin is enabled

​
Sign In

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

const result = await client.signIn.email({
  email: 'user@example.com',
  password: 'securePassword123'
})
​
email
string
required
User’s email address
​
password
string
required
User’s password
​
user
object
Authenticated user object
​
session
object
Created session

​
Forget Password

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

await client.forgetPassword({
  email: 'user@example.com',
  redirectTo: '/reset-password'
})
​
email
string
required
Email address to send reset link
​
redirectTo
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'
})
​
newPassword
string
required
New password
​
token
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'
})
​
email
string
required
Email to send OTP code
​
type
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'
})
​
email
string
required
Email address
​
otp
string
required
6-digit OTP code from email
​
user
object
Authenticated user object
​
session
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'
})
​
provider
string
required
OAuth provider: google, github, microsoft, or facebook
​
callbackURL
string
URL to redirect after authentication
Supported Providers (from src/lib/auth/auth.ts:45-78):
Required Environment Variables:
  • GOOGLE_CLIENT_ID
  • GOOGLE_CLIENT_SECRET
Scopes: email, profile
Required Environment Variables:
  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET
Scopes: user:email
Required Environment Variables:
  • MICROSOFT_CLIENT_ID
  • MICROSOFT_CLIENT_SECRET
  • MICROSOFT_TENANT_ID (optional, defaults to ‘common’)
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>
}
​
session
object | null
Current session or null if not authenticated

​
Sign Out

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

await signOut()

​
Organization Endpoints

​
Create Organization

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

const { data } = await client.organization.create({
  name: 'Acme Corp',
  slug: 'acme-corp'
})
​
name
string
required
Organization name
​
slug
string
required
URL-friendly slug
​
organization
object
Created organization

​
Invite Member

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

await client.organization.inviteMember({
  organizationId: 'org_123',
  email: 'member@example.com',
  role: 'member'
})
​
organizationId
string
required
Organization ID
​
email
string
required
Email of person to invite
​
role
string
required
Role: member or admin

​
Error Responses

All endpoints return standard HTTP status codes:
​
400
Bad Request
Invalid request parameters or validation error
​
401
Unauthorized
Authentication required or invalid credentials
​
403
Forbidden
Insufficient permissions
​
404
Not Found
Resource not found
​
500
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
}

​
Next Steps

Authentication Overview

Learn about authentication features

Database Schema

View auth-related database tables

Build docs developers (and LLMs) love

Get started for freeTalk to us