Better Auth UI

Add programmatic API key management with create, copy, and revoke flows to your authentication settings.

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.

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

Install the Better Auth plugin

Install the @better-auth/api-key package and add it to your Better Auth server config:

lib/auth.ts

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

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

Install the matching client plugin

Add apiKeyClient() to your auth client so authClient.apiKey.* methods are available:

lib/auth-client.ts

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

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

Install the UI plugin

Run the shadcn CLI to install the API key components and the apiKeyPlugin() factory into your project:

npx shadcn@latest add https://better-auth-ui.com/r/api-key.json

This drops the following into your codebase:

src/lib/auth/auth-plugin.ts — local AuthPlugin typing widener
src/lib/auth/api-key-plugin.ts — apiKeyPlugin() factory
src/components/auth/api-key/api-keys.tsx — the API keys security card
src/components/auth/api-key/api-key.tsx — individual API key row with delete control
src/components/auth/api-key/api-keys-empty.tsx — empty state shown when no keys exist
src/components/auth/api-key/api-key-skeleton.tsx — skeleton shown while keys are loading
src/components/auth/api-key/create-api-key-dialog.tsx — dialog for creating a new key
src/components/auth/api-key/new-api-key-dialog.tsx — dialog showing the newly created key with copy button
src/components/auth/api-key/delete-api-key-dialog.tsx — confirmation dialog for revoking a key
src/components/auth/api-key/organization-api-keys.tsx — owner-gated wrapper that renders <ApiKeys /> scoped to the active organization

Register the UI plugin

Pass apiKeyPlugin() to <AuthProvider>:

components/providers.tsx

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>

API keys

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

Prop

Type

`<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" }:

components/providers.tsx

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>

lib/auth.ts

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

Prop

Type

Options

Prop

Type

Localization

Prop

Type

API Key

Setup

Install the Better Auth plugin

Install the matching client plugin

Install the UI plugin

Register the UI plugin

Components

`<ApiKeys />`

API keys

`<OrganizationApiKeys />`

Options

Localization

On this page