Agent Auth Plugin

@better-auth/agent-auth is the official server implementation of the Agent Auth Protocol. When you enable it, your Quickback worker becomes an Agent Auth provider: AI agents can register, request scoped capability grants from a real user, get approved through device-authorization or CIBA, and then call your API with short-lived signed JWTs.

What gets enabled

Adding agentAuth to your auth config force-enables two more plugins:

There's no useful Agent Auth deployment without these — the compiler auto-adds them so you don't trip over a confusing runtime error.

The full Bearer matrix on the agent surface (everything reached through /mcp and the agent-auth REST projection):

Cookie auth is not forwarded into /mcp — bearer is the only channel, and CSRF surface is zero.

Configuration

import { defineAuth, defineConfig, defineDatabase, defineRuntime } from "@quickback/compiler";

export default defineConfig({
  name: "acme-api",
  providers: {
    runtime: defineRuntime("cloudflare"),
    database: defineDatabase("cloudflare-d1"),
    auth: defineAuth("better-auth", {
      emailAndPassword: { enabled: true },
      plugins: {
        agentAuth: {
          providerName: "Acme",
          providerDescription: "Acme APIs for AI agents.",
          modes: ["delegated", "autonomous"],
          defaultHostCapabilities: ["GET", "HEAD"],
        },
      },
    }),
  },
});

The plain-flag form is also valid — use it when you don't need to override any defaults:

auth: defineAuth("better-auth", {
  plugins: ["agentAuth"],
})

Options

Most of the underlying plugin's surface (capability list, onExecute, custom approval-method resolver, onEvent audit hook) isn't projected through the compiler in v1 — see "Limitations".

Routes

When the plugin is enabled the compiler emits:

• GET /.well-known/agent-configuration — discovery document with issuer, endpoints, supported modes, default location.
• All of the plugin's own endpoints, mounted by Better Auth under /auth/v1/agent/*.

The Account SPA gets a new route at /agents/approve for device-code approval. The plugin's deviceAuthorizationPage is automatically pinned at ${ACCOUNT_URL}/agents/approve.

Approval flow

1. The agent calls /auth/v1/agent/register to create itself, then requests a capability grant.
2. The user enters the device code at ${ACCOUNT_URL}/agents/approve (or follows the deep-link the agent showed them).
3. The Account SPA fetches the pending request, shows the agent name + provider name + the capabilities being requested, with a "Step-up" badge on any capability whose approvalStrength is "webauthn".
4. User clicks Authorize (or Deny). Approval grants the capabilities; denial leaves the request pending.
5. The agent polls or receives the token via the configured method, then calls capabilities with Authorization: Bearer <agent-jwt>.

You revoke an agent at any time from your account settings (or directly via the BA admin API).

Schema

The plugin adds tables for agent, host, grant, and approval. They're created automatically by auth migrate / auth generate — no manual Drizzle work needed.

OpenAPI capability projection (default on)

When agentAuth is enabled, the compiler emits src/lib/openapi-spec.ts (the project's full OpenAPI spec inlined as a const) and wires createFromOpenAPI(openapiSpec, { ... }) into the agentAuth(...) call. Every operation with an operationId becomes a capability. No manual capability list required.

How requests flow:

1. Agent calls POST /capability/execute with its agent JWT.
2. The plugin verifies JWT + grant + constraints, then runs onExecute.
3. onExecute (the plugin's built-in proxy) makes a self-fetch to the worker's own URL (env.BETTER_AUTH_URL).
4. resolveHeaders mints a Better Auth JWT with sub: agentSession.user.id so the inner request looks like an authenticated user call.
5. The worker's JWT fast-path picks it up, populates ctx, and the full firewall + access + masking pipeline runs.

Default approval strength: GET → "session", POST/PUT/PATCH/DELETE → "webauthn". Override with the approvalStrength option.

To opt out and wire capabilities by hand:

auth: defineAuth("better-auth", {
  plugins: {
    agentAuth: { fromOpenAPI: false },
  },
})

When fromOpenAPI: false, the emitted call has capabilities: [] and no proxy — you write the capability list + onExecute in your own lib/auth.ts overrides.

Limitations (v1)

• WebAuthn step-up isn't wired in the approval UI yet. Capabilities tagged approvalStrength: "webauthn" show a Step-up badge but the actual escalation call isn't made — the upstream API for that escalation is still settling. Until it lands, those capabilities will fail server-side regardless of approval.
• No CLI helpers for listing / revoking agents. Use the BA admin API directly.
• Self-fetch on Cloudflare Workers adds one subrequest per capability call (~50ms). For typical agent traffic this is fine; for very high-frequency agents consider pinning a custom onExecute that uses app.request() for in-process routing.
• @better-auth/agent-auth 0.4.5 ships ESM-only exports without a require condition. The compiler image patches the package's package.json at install time so the Better Auth CLI's auth generate step (jiti / CJS) can resolve it. Remove the patch in the Dockerfile when upstream ships proper exports.

Why bearer-only?

The MCP and agent surfaces are server-to-server by nature. Cookies on those surfaces add CSRF surface for no benefit (no browser callers), and x-api-key was the legacy apiKey-plugin path that fragments the auth model. Bearer is the one true channel here. If your project still wants API-key auth, configure the apiKey plugin to accept its key via Authorization: Bearer so everything stays one channel.