API

When you create a new Better Auth instance, it provides you with an api object. This object exposes every endpoint that exist in your better auth instance. And you can use this to interact with Better Auth server side.

Any endpoint added to Better Auth, whether from plugins or the core, will be accessible through the api object.

Calling API Endpoints on the Server

To call an API endpoint on the server, import your auth instance and call the endpoint using the api object.

import { betterAuth } from "better-auth";
import { headers } from "next/headers";
 
export const auth = betterAuth({
    //...
})
 
// calling get session on the server
await auth.api.getSession({
    headers: headers() //some endpoint might require headers
})

Body, Headers, Query

Unlike the client, the server needs the values to be passed as an object with the key body for the body, headers for the headers, and query for query parameters.

await auth.api.getSession({
    headers: headers()
})
 
await auth.api.signInEmail({
    body: {
        email: "john@doe.com",
        password: "password"
    },
    headers: headers() // optional but would be useful to get the user IP, user agent, etc.
})
 
await auth.api.verifyEmail({
    query: {
        token: "my_token"
    }
})

Getting headers and Response Object

When you invoke an API endpoint on the server, it will return a standard JavaScript object or array directly as it's just a regular function call.

But there are times where you might want to get the headers or the Response object instead. For example, if you need to get the cookies or the headers.

Getting headers

To get the headers, you can pass the returnHeaders option to the endpoint.

const { headers, response } = await auth.api.signUpEmail({
	returnHeaders: true,
	body: {
		email: "john@doe.com",
		password: "password",
		name: "John Doe",
	},
});

The headers will be a Headers object. Which you can use to get the cookies or the headers.

const cookies = headers.get("set-cookie");
const headers = headers.get("x-custom-header");

Getting Response Object

To get the Response object, you can pass the asResponse option to the endpoint.

const response = await auth.api.signInEmail({
    body: {
        email: "",
        password: ""
    },
    asResponse: true
})

Error Handling

When you call an API endpoint in the server, it will throw an error if the request fails. You can catch the error and handle it as you see fit. The error instance is an instance of APIError.

import { APIError } from "better-auth/api";
 
try {
    await auth.api.signInEmail({
        body: {
            email: "",
            password: ""
        }
    })
} catch (error) {
    if (error instanceof APIError) {
        console.log(error.message, error.status)
    }
}