API Key

The API key plugin adds programmatic API key management to your authentication UI. Users can create, copy, and revoke API keys from a security card in account settings. New keys can use a configurable expiration interval, and each listed key shows when it expires.

It contributes:

• An <ApiKeys /> card to the security settings tab for user-owned keys
• An <OrganizationApiKeys /> card to <OrganizationSettings /> for organization-owned keys (opt-in via apiKeyPlugin({ organization: true }). Requires the organization plugin and a matching server-side API key config)

Setup

import { betterAuth } from "better-auth"
import { apiKey } from "@better-auth/api-key"

export const auth = betterAuth({
  // ...
  plugins: [
    apiKey() 
  ]
})

import { createAuthClient } from "better-auth/react"
import { apiKeyClient } from "@better-auth/api-key/client"

export const authClient = createAuthClient({
  plugins: [apiKeyClient()] 
})

npx shadcn@latest add @better-auth-ui/api-key

import { AuthProvider } from "@/components/auth/auth-provider"
import { apiKeyPlugin } from "@/lib/auth/api-key-plugin"

import { authClient } from "@/lib/auth-client"

<AuthProvider
  authClient={authClient}
  plugins={[
    apiKeyPlugin() 
  ]}
>
  {children}
</AuthProvider>

Configure expiration

The create dialog offers 30 days, 90 days, and Never by default. It initially selects 30 days. Configure the choices through apiKeyPlugin():

apiKeyPlugin({
  keyExpiration: {
    intervals: [7, 30, 90],
    defaultInterval: 30,
    allowNever: true
  }
})

intervals and defaultInterval use days. Better Auth receives the selected lifetime as seconds.

Keep the UI choices within the limits in your Better Auth server configuration:

apiKey({
  keyExpiration: {
    minExpiresIn: 7,
    maxExpiresIn: 90,
    defaultExpiresIn: null
  }
})

When allowNever is enabled, selecting Never sends no custom interval. Better Auth will still apply defaultExpiresIn if the server defines one, so set allowNever: false in the UI when your server always requires expiration.

To remove the expiration field and rely entirely on the server default:

apiKeyPlugin({ keyExpiration: false })

Components

<ApiKeys />

The security settings page shows <ApiKeys /> when the layout renders plugin securityCards. Add apiKeyPlugin() to plugins to provide this card.

Usage

import { ApiKeys } from "@/components/auth/api-key/api-keys"

<ApiKeys />

Props

<OrganizationApiKeys />

A thin wrapper around <ApiKeys /> that resolves the active organization via useActiveOrganization and forwards its id. Rendered inside <OrganizationSettings /> only when the plugin is registered with { organization: true }.

To enable, opt in on the UI plugin and add a matching API key configuration to your Better Auth server config. The plugin uses a fixed configId of "organization", so the server entry must be { configId: "organization", references: "organization" }:

import { AuthProvider } from "@/components/auth/auth-provider"
import { apiKeyPlugin } from "@/lib/auth/api-key-plugin"

import { authClient } from "@/lib/auth-client"

<AuthProvider
  authClient={authClient}
  plugins={[
    apiKeyPlugin({ organization: true }) 
  ]}
>
  {children}
</AuthProvider>

import { betterAuth } from "better-auth"
import { apiKey } from "@better-auth/api-key"
import { organization } from "better-auth/plugins"

export const auth = betterAuth({
  // ...
  plugins: [
    organization(),
    apiKey([
      { configId: "default", references: "user" },
      { configId: "organization", references: "organization" } 
    ])
  ]
})

See the Better Auth docs for role-based permissions on organization-owned keys.

Usage

import { OrganizationApiKeys } from "@/components/auth/api-key/organization-api-keys"

<OrganizationApiKeys />

Props

Options

Localization

Lifecycle controls

<ApiKeys /> lets users create, rename, and delete keys. The create form exposes the name, configuration, expiration, and organization. The list shows status, remaining requests, request usage, and the last request time as read-only values.

The built-in dialog does not show metadata because metadata belongs to the application. For metadata, build a custom form with useCreateApiKey. Map named fields or application state to the metadata object. Do not show a raw JSON editor. If metadata affects trusted behavior, validate it in a server route.

Better Auth reserves enablement, permissions, quotas, refill rules, and rate limits for server-side creation and updates. Configure those values in trusted server code instead of exposing them in the account UI.

apiKeyPlugin({
  configurations: [
    { id: "default", label: "Personal", organization: false },
    { id: "organization", label: "Organization", organization: true }
  ],
  pageSize: 20
})

The server must define every listed configId. Use useUpdateApiKey for a custom rename surface.