Interactive API reference
Expose authentication API documentation in a browser for developers and integrators.
Better Auth · Const
openAPI
The openAPI plugin adds a Scalar-based OpenAPI reference for Better Auth, covering core and plugin endpoints. It also exposes the generated schema programmatically.
How it works
The openAPI plugin adds a Scalar-powered OpenAPI reference to Better Auth. Install it in the auth configuration, then browse the default reference route or call the server API to generate the schema directly.
Syntax
openAPI()Returns
auth.api.generateOpenAPISchema() returns the generated Open API schema as a JSON object.
Key points
- openAPI() adds an Open API reference to a Better Auth instance.
- The reference includes both core authentication endpoints and endpoints contributed by plugins.
- The default browser route for the generated reference is /api/auth/reference.
- Plugin-contributed endpoints are grouped according to the plugin that added them.
- Core endpoints appear under the Default group.
- Generated model schemas are collected under the Models group.
- The server API can return the generated schema as a JSON object.
Common mistakes
- Client generators and related tooling must support OpenAPI 3.1 semantics when consuming the generated schema.
- A custom reference path is relative to, and appended to, the authentication server's base path.
Example: Enable Open API and generate its schema
import { betterAuth } from "better-auth"
import { openAPI } from "better-auth/plugins"
export const auth = betterAuth({
plugins: [openAPI()],
})
const schema = await auth.api.generateOpenAPISchema()
console.log(schema)Registers the Open API plugin and obtains the generated schema as a JSON object.
When to use it
Schema-driven tooling
Create client libraries or feed the authentication contract into compatible API tooling.
Endpoint testing
Inspect and manually invoke Better Auth endpoints during development or troubleshooting.
Interview questions
QHow do you enable the Better Auth Open API plugin?
The plugin is enabled by importing openAPI from better-auth/plugins and adding openAPI() to the plugins array passed to betterAuth. It exposes the reference at /api/auth/reference by default.
Follow-up: How can the route be changed? Set the plugin's path option to another path, remembering that the value is appended to the auth server base path.
QHow are endpoints organized in the generated reference?
The reference groups plugin endpoints by plugin name, places core endpoints in Default, and places model schemas in Models. Scalar renders the reference and provides interactive endpoint testing.
Follow-up: What powers the interactive UI? Scalar is the library used to display and test the generated reference.
QHow do you retrieve the generated OpenAPI schema programmatically?
Call auth.api.generateOpenAPISchema() to obtain the generated Open API schema directly as a JSON object. The schema follows the OpenAPI 3.1.1 specification.
Follow-up: What compatibility concern applies when using it for code generation? The consuming generator or tool must understand OpenAPI 3.1 semantics.
Related
betterAuthauth.api.generateOpenAPISchemaDefaultModelsScalar