​
ADR-0011: Better Auth bearer plugin required for CLI API key creation

​
Status

Accepted

​
Tags

cli, grm, better-auth, bearer, api-key, authentication, bun

​
Decision

The bearer plugin is added to the Bun backend’s Better Auth config alongside deviceAuthorization and apiKey. This allows the CLI to call POST /api/auth/api-key/create using Authorization: Bearer <access_token> immediately after the device flow completes.

​
Why

Better Auth’s apiKey plugin authenticates createApiKey requests via session cookie by default. A CLI cannot present a browser session cookie — it only has the access token returned by the device flow. Without the bearer plugin, Better Auth rejects the CLI’s createApiKey call with a 401. The alternative — having the browser’s /device approval page create the API key and surface it to the CLI — would require a polling or callback mechanism to pass the key from browser to terminal, significantly increasing complexity.

​
Consequences

The bearer plugin must remain in the Better Auth config for as long as the CLI exists. Removing it silently breaks grm auth login at the API key creation step with a 401 error, not a descriptive failure — making it hard to diagnose without knowing this ADR.

​
Rules for agents

  • Do not remove the bearer plugin from the Better Auth config without also removing the CLI’s CreateAPIKey call
  • The three CLI-required plugins must always appear together: deviceAuthorization, apiKey, bearer
  • If adding a new Better Auth plugin that restricts bearer token usage, verify it does not break the CLI login flow