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 registry add @better-auth-ui=https://better-auth-ui.com/r/{style}/{name}.json

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 <ApiKeys /> security card is rendered on the security settings page when your layout renders each plugin's securityCards (as the example SecuritySettings does) and apiKeyPlugin() is in plugins.

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