agent-auth/openapi

14 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

createFromOpenAPI - OpenAPI adapter overview

createFromOpenAPI reads an OpenAPI 3.x spec and produces capabilities (one per operationId), input/output JSON Schemas, proxy onExecute handler, and optionally providerName/providerDescription from info section. Every operation with an operationId becomes a capability. Path, query, and header parameters plus JSON request body are merged into single input schema. 200/201 response body becomes output schema.

createFromOpenAPI basic example

Example: const spec = await fetch('https://api.example.com/openapi.json').then((r) => r.json()); export const auth = betterAuth({ plugins: [agentAuth({ ...createFromOpenAPI(spec, { baseUrl: 'https://api.example.com' }), })], });

createFromOpenAPI resolveHeaders for upstream authentication

Use resolveHeaders in createFromOpenAPI options to inject credentials each request needs, such as internal service token or user-scoped access token looked up from agentSession. The proxy handler calls upstream API on behalf of the agent with these injected headers.

createFromOpenAPI defaultHostCapabilities option

Control which capabilities are auto-granted to new hosts using defaultHostCapabilities. Value can be: true for all capabilities, single HTTP method string, array of method strings, or callback function receiving full runtime context.

createFromOpenAPI approvalStrength per HTTP method

Map HTTP methods to approvalStrength so mutating operations require stronger user verification while reads use normal session. Example: { GET: 'session', POST: 'webauthn', PUT: 'webauthn', DELETE: 'webauthn' }

createFromOpenAPI location for per-capability URLs

Set location option in createFromOpenAPI so every derived capability gets that URL. Agents call it directly with agent JWT instead of going through default execute endpoint. Useful when you want agent to hit real API URL and handle session in own middleware rather than proxying through onExecute.

createFromOpenAPI lower-level helpers

The OpenAPI adapter exports: fromOpenAPI(spec) returns Capability[] only (no handler, no host caps); createOpenAPIHandler(spec, opts) returns only onExecute proxy handler to pair with hand-written capabilities or filtered spec. Import from @better-auth/agent-auth/openapi.

Open API reference URL

The Open API reference is served at /api/auth/reference by default. Plugin endpoints are grouped by plugin name, core endpoints are grouped under 'Default', and model schemas are grouped under 'Models'.

Generate Open API schema programmatically

To get the generated Open API schema directly as JSON, call auth.api.generateOpenAPISchema(). This returns the Open API schema as a JSON object.

Open API plugin configuration options

The Open API plugin accepts the following configuration options: path (default '/api/auth/reference') - the path where the reference is served; disableDefaultReference (default false) - disables the default Scalar UI if true; theme (default 'default') - changes the theme of the reference page; nonce (default undefined) - passes a nonce string to inline scripts for CSP compliance.

Open API specification version

The Open API reference is generated using the OpenAPI 3.1.1 specification. When using the generated schema with client generators or other tooling, ensure they support OpenAPI 3.1 semantics.

Scalar integration with multiple sources

When using Hono with Scalar for OpenAPI documentation, Better Auth can be added as an additional source by providing the URL /api/auth/open-api/generate-schema as a source endpoint alongside other API sources.

Open API plugin uses Scalar

The Open API plugin uses the Scalar library to display the Open API reference. Scalar provides a way to view and test endpoints through a 'Try it out' button where users can provide required parameters.

Open API plugin development status

The Open API plugin is still in the early stages of development. The team is working on adding more features and filling in the gaps.

Give your agent this brain