Auth API
Better Auth provides a comprehensive authentication API. All endpoints are under /api/auth/.
Endpoints
Sign Up
Create a new user account with email and password.
POST /api/auth/sign-up/emailRequest Body:
{
"email": "user@example.com",
"password": "securepassword123",
"name": "John Doe"
}Response:
{
"user": {
"id": "user_123",
"email": "user@example.com",
"name": "John Doe",
"emailVerified": false,
"createdAt": "2024-01-01T00:00:00.000Z"
}
}Sign In
Authenticate an existing user.
POST /api/auth/sign-in/emailRequest Body:
{
"email": "user@example.com",
"password": "securepassword123"
}Response:
{
"user": {
"id": "user_123",
"email": "user@example.com",
"name": "John Doe"
},
"session": {
"id": "session_456",
"expiresAt": "2024-01-08T00:00:00.000Z"
}
}Sign Out
End the current session.
POST /api/auth/sign-outResponse:
{
"success": true
}Get Session
Get the current user session.
GET /api/auth/sessionResponse (Authenticated):
{
"user": {
"id": "user_123",
"email": "user@example.com",
"name": "John Doe",
"plan": "pro"
},
"session": {
"id": "session_456",
"expiresAt": "2024-01-08T00:00:00.000Z"
}
}Response (Not Authenticated):
{
"user": null,
"session": null
}OAuth Endpoints
Initiate OAuth
Redirect the user to OAuth provider.
GET /api/auth/sign-in/[provider]Providers: google, github, discord, etc.
Query Parameters:
| Parameter | Description |
|---|---|
callbackURL | URL to redirect after auth |
Example:
GET /api/auth/sign-in/google?callbackURL=/dashboardOAuth Callback
Handles OAuth provider callback (internal).
GET /api/auth/callback/[provider]Password Reset
Request Reset
Send password reset email.
POST /api/auth/forget-passwordRequest Body:
{
"email": "user@example.com",
"redirectTo": "/reset-password"
}Response:
{
"success": true
}Reset Password
Set a new password with reset token.
POST /api/auth/reset-passwordRequest Body:
{
"token": "reset_token_from_email",
"newPassword": "newsecurepassword123"
}Response:
{
"success": true
}Email Verification
Request Verification
Resend verification email.
POST /api/auth/send-verification-emailRequest Body:
{
"email": "user@example.com"
}Verify Email
Verify email with token.
POST /api/auth/verify-emailRequest Body:
{
"token": "verification_token"
}Client-Side Usage
React
import { signIn, signUp, signOut, useSession } from "@/lib/auth/client"
// Sign up
const result = await signUp.email({
email: "user@example.com",
password: "password123",
name: "John",
})
// Sign in
await signIn.email({
email: "user@example.com",
password: "password123",
})
// OAuth sign in
await signIn.social({
provider: "google",
callbackURL: "/dashboard",
})
// Sign out
await signOut()
// Get session (hook)
function Component() {
const { data: session, isPending } = useSession()
// ...
}Error Codes
| Code | Description |
|---|---|
USER_NOT_FOUND | No user with this email |
INVALID_PASSWORD | Incorrect password |
EMAIL_NOT_VERIFIED | Email verification required |
USER_ALREADY_EXISTS | Email already registered |
INVALID_TOKEN | Reset/verification token invalid or expired |
SESSION_EXPIRED | Session has expired |
Last updated on