API Key

The API Key plugin allows you to create and manage API keys for your application. It provides a way to authenticate and authorize API requests by verifying API keys.

Features

• Create, manage, and verify API keys
• Built-in rate limiting
• Custom expiration times, remaining count, and refill systems
• metadata for API keys
• Custom prefix
• Sessions from API keys
• Secondary storage support for high-performance API key lookups

Installation

import { betterAuth } from "better-auth"
import { apiKey } from "better-auth/plugins"

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

npx @better-auth/cli migrate

npx @better-auth/cli generate

import { createAuthClient } from "better-auth/client"
import { apiKeyClient } from "better-auth/client/plugins"

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

Usage

You can view the list of API Key plugin options here.

Create an API key

const { data, error } = await authClient.apiKey.create({    name: 'project-api-key',    expiresIn: 60 * 60 * 24 * 7,    prefix: 'project-api-key',    metadata: { someKey: 'someValue' },});

const data = await auth.api.createApiKey({    body: {        name: 'project-api-key',        expiresIn: 60 * 60 * 24 * 7,        userId: "user-id", // server-only        prefix: 'project-api-key',        remaining: 100, // server-only        metadata: { someKey: 'someValue' },        refillAmount: 100, // server-only        refillInterval: 1000, // server-only        rateLimitTimeWindow: 1000, // server-only        rateLimitMax: 100, // server-only        rateLimitEnabled: true, // server-only        permissions, // server-only    },});

Result

It'll return the ApiKey object which includes the key value for you to use. Otherwise if it throws, it will throw an APIError.

Verify an API key

const permissions = { // Permissions to check are optional.  projects: ["read", "read-write"],}const { data, error } = await authClient.apiKey.verify({    key: "your_api_key_here", // required    permissions,});

const permissions = { // Permissions to check are optional.  projects: ["read", "read-write"],}const data = await auth.api.verifyApiKey({    body: {        key: "your_api_key_here", // required        permissions,    },});

Result

type Result = {
  valid: boolean;
  error: { message: string; code: string } | null;
  key: Omit<ApiKey, "key"> | null;
};

Get an API key

const { data, error } = await authClient.apiKey.get({    query: {        id: "some-api-key-id", // required    },});

const data = await auth.api.getApiKey({    query: {        id: "some-api-key-id", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

Result

You'll receive everything about the API key details, except for the key value itself. If it fails, it will throw an APIError.

type Result = Omit<ApiKey, "key">;

Update an API key

const { data, error } = await authClient.apiKey.update({    keyId: "some-api-key-id", // required    name: "some-api-key-name",});

const data = await auth.api.updateApiKey({    body: {        keyId: "some-api-key-id", // required        userId: "some-user-id", // server-only        name: "some-api-key-name",        enabled: true, // server-only        remaining: 100, // server-only        refillAmount: 100, // server-only        refillInterval: 1000, // server-only        metadata: { "key": "value" }, // server-only        expiresIn: 60 * 60 * 24 * 7, // server-only        rateLimitEnabled: true, // server-only        rateLimitTimeWindow: 1000, // server-only        rateLimitMax: 100, // server-only        permissions, // server-only    },});

Result

If fails, throws APIError. Otherwise, you'll receive the API Key details, except for the key value itself.

Delete an API Key

const { data, error } = await authClient.apiKey.delete({    keyId: "some-api-key-id", // required});

const data = await auth.api.deleteApiKey({    body: {        keyId: "some-api-key-id", // required    },    // This endpoint requires session cookies.    headers: await headers(),});

Result

If fails, throws APIError. Otherwise, you'll receive:

type Result = {
  success: boolean;
};

List API keys

const { data, error } = await authClient.apiKey.list();

const data = await auth.api.listApiKeys({    // This endpoint requires session cookies.    headers: await headers(),});

Result

If fails, throws APIError. Otherwise, you'll receive:

type Result = ApiKey[];

Delete all expired API keys

This function will delete all API keys that have an expired expiration date.

const { data, error } = await authClient.apiKey.deleteAllExpiredApiKeys();

const data = await auth.api.deleteAllExpiredApiKeys();

Sessions from API keys

Any time an endpoint in Better Auth is called that has a valid API key in the headers, you can automatically create a mock session to represent the user by enabling sessionForAPIKeys option.

export const auth = betterAuth({
  plugins: [
    apiKey({
      enableSessionForAPIKeys: true,
    }),
  ],
});

const session = await auth.api.getSession({
      headers: new Headers({
            'x-api-key': apiKey,
      }),
});

The default header key is x-api-key, but this can be changed by setting the apiKeyHeaders option in the plugin options.

export const auth = betterAuth({
  plugins: [
    apiKey({
      apiKeyHeaders: ["x-api-key", "xyz-api-key"], // or you can pass just a string, eg: "x-api-key"
    }),
  ],
});

Or optionally, you can pass an apiKeyGetter function to the plugin options, which will be called with the GenericEndpointContext, and from there, you should return the API key, or null if the request is invalid.

export const auth = betterAuth({
  plugins: [
    apiKey({
      apiKeyGetter: (ctx) => {
        const has = ctx.request.headers.has("x-api-key");
        if (!has) return null;
        return ctx.request.headers.get("x-api-key");
      },
    }),
  ],
});

Storage Modes

The API Key plugin supports multiple storage modes for flexible API key management, allowing you to choose the best strategy for your use case.

Storage Mode Options

"database" (Default)

Store API keys only in the database adapter. This is the default mode and requires no additional configuration.

export const auth = betterAuth({
  plugins: [
    apiKey({
      storage: "database", // Default, can be omitted
    }),
  ],
});

"secondary-storage"

Store API keys only in secondary storage (e.g., Redis). No fallback to database. Best for high-performance scenarios where all keys are migrated to secondary storage.

import { createClient } from "redis";
import { betterAuth } from "better-auth";
import { apiKey } from "better-auth/plugins";

const redis = createClient();
await redis.connect();

export const auth = betterAuth({
  secondaryStorage: {
    get: async (key) => await redis.get(key),
    set: async (key, value, ttl) => {
      if (ttl) await redis.set(key, value, { EX: ttl });
      else await redis.set(key, value);
    },
    delete: async (key) => await redis.del(key),
  },
  plugins: [
    apiKey({
      storage: "secondary-storage",
    }),
  ],
});

Secondary Storage with Fallback

Check secondary storage first, then fallback to database if not found.

Read behavior:

• Checks secondary storage first
• If not found, queries the database
• Automatically populates secondary storage when falling back to database (cache warming)
• Ensures frequently accessed keys stay in cache over time

Write behavior:

• Writes to both database and secondary storage
• Ensures consistency between both storage layers

export const auth = betterAuth({
  secondaryStorage: {
    get: async (key) => await redis.get(key),
    set: async (key, value, ttl) => {
      if (ttl) await redis.set(key, value, { EX: ttl });
      else await redis.set(key, value);
    },
    delete: async (key) => await redis.del(key),
  },
  plugins: [
    apiKey({
      storage: "secondary-storage",
      fallbackToDatabase: true,
    }),
  ],
});

Custom Storage Methods

You can provide custom storage methods specifically for API keys, overriding the global secondaryStorage configuration:

export const auth = betterAuth({
  plugins: [
    apiKey({
      storage: "secondary-storage",
      customStorage: {
        get: async (key) => {
          // Custom get logic for API keys
          return await customStorage.get(key);
        },
        set: async (key, value, ttl) => {
          // Custom set logic for API keys
          await customStorage.set(key, value, ttl);
        },
        delete: async (key) => {
          // Custom delete logic for API keys
          await customStorage.delete(key);
        },
      },
    }),
  ],
});

Rate Limiting

Every API key can have its own rate limit settings. The built-in rate-limiting applies whenever an API key is validated, which includes:

• When verifying an API key via the /api-key/verify endpoint
• When using API keys for session creation (if enableSessionForAPIKeys is enabled), rate limiting applies to all endpoints that use the API key

For other endpoints/methods that don't use API keys, you should utilize Better Auth's built-in rate-limiting.

You can refer to the rate-limit default configurations below in the API Key plugin options.

An example default value:

export const auth = betterAuth({
  plugins: [
    apiKey({
      rateLimit: {
        enabled: true,
        timeWindow: 1000 * 60 * 60 * 24, // 1 day
        maxRequests: 10, // 10 requests per day
      },
    }),
  ],
});

For each API key, you can customize the rate-limit options on create.

const apiKey = await auth.api.createApiKey({
  body: {
    rateLimitEnabled: true,
    rateLimitTimeWindow: 1000 * 60 * 60 * 24, // 1 day
    rateLimitMax: 10, // 10 requests per day
  },
  headers: user_headers,
});

How does it work?

The rate limiting system uses a sliding window approach:

1. First Request: When an API key is used for the first time (no previous lastRequest), the request is allowed and requestCount is set to 1.

2. Within Window: For subsequent requests within the timeWindow, the requestCount is incremented. If requestCount reaches rateLimitMax, the request is rejected with a RATE_LIMITED error code.

3. Window Reset: If the time since the last request exceeds the timeWindow, the window resets: requestCount is reset to 1 and lastRequest is updated to the current time.

4. Rate Limit Exceeded: When a request is rejected due to rate limiting, the error response includes a tryAgainIn value (in milliseconds) indicating how long to wait before the window resets.

Disabling Rate Limiting:

• Globally: Set rateLimit.enabled: false in plugin options
• Per Key: Set rateLimitEnabled: false when creating or updating an API key
• Null Values: If rateLimitTimeWindow or rateLimitMax is null, rate limiting is effectively disabled for that key

When rate limiting is disabled (globally or per-key), requests are still allowed but lastRequest is updated for tracking purposes.

Remaining, refill, and expiration

The remaining count is the number of requests left before the API key is disabled. The refill interval is the interval in milliseconds where the remaining count is refilled when the interval has passed since the last refill (or since creation if no refill has occurred yet). The expiration time is the expiration date of the API key.

How does it work?

Remaining:

Whenever an API key is used, the remaining count is updated. If the remaining count is null, then there is no cap to key usage. Otherwise, the remaining count is decremented by 1. If the remaining count is 0, then the API key is disabled & removed.

refillInterval & refillAmount:

Whenever an API key is created, the refillInterval and refillAmount are set to null by default. This means that the API key will not be refilled automatically. However, if both refillInterval & refillAmount are set, then whenever the API key is used:

• The system checks if the time since the last refill (or since creation if no refill has occurred) exceeds the refillInterval
• If the interval has passed, the remaining count is reset to refillAmount (not incremented)
• The lastRefillAt timestamp is updated to the current time

Expiration:

Whenever an API key is created, the expiresAt is set to null. This means that the API key will never expire. However, if the expiresIn is set, then the API key will expire after the expiresIn time.

Custom Key generation & verification

You can customize the key generation and verification process straight from the plugin options.

Here's an example:

export const auth = betterAuth({
  plugins: [
    apiKey({
      customKeyGenerator: (options: {
        length: number;
        prefix: string | undefined;
      }) => {
        const apiKey = mySuperSecretApiKeyGenerator(
          options.length,
          options.prefix
        );
        return apiKey;
      },
      customAPIKeyValidator: async ({ ctx, key }) => {
        const res = await keyService.verify(key)
        return res.valid
      },
    }),
  ],
});

export const auth = betterAuth({
  plugins: [
    apiKey({
      customKeyGenerator: () => {
        return crypto.randomUUID();
      },
      defaultKeyLength: 36, // Or whatever the length is
    }),
  ],
});

If an API key is validated from your customAPIKeyValidator, we still must match that against the database's key. However, by providing this custom function, you can improve the performance of the API key verification process, as all failed keys can be invalidated without having to query your database.

Metadata

We allow you to store metadata alongside your API keys. This is useful for storing information about the key, such as a subscription plan for example.

To store metadata, make sure you haven't disabled the metadata feature in the plugin options.

export const auth = betterAuth({
  plugins: [
    apiKey({
      enableMetadata: true,
    }),
  ],
});

Then, you can store metadata in the metadata field of the API key object.

const apiKey = await auth.api.createApiKey({
  body: {
    metadata: {
      plan: "premium",
    },
  },
});

You can then retrieve the metadata from the API key object.

const apiKey = await auth.api.getApiKey({
  body: {
    keyId: "your_api_key_id_here",
  },
});

console.log(apiKey.metadata.plan); // "premium"

API Key plugin options

apiKeyHeaders string | string[];

The header name to check for API key. Default is x-api-key.

customAPIKeyGetter (ctx: GenericEndpointContext) => string | null

A custom function to get the API key from the context.

customAPIKeyValidator (options: { ctx: GenericEndpointContext; key: string; }) => boolean | Promise<boolean>

A custom function to validate the API key.

customKeyGenerator (options: { length: number; prefix: string | undefined; }) => string | Promise<string>

A custom function to generate the API key.

startingCharactersConfig { shouldStore?: boolean; charactersLength?: number; }

Customize the starting characters configuration.

defaultKeyLength number

The length of the API key. Longer is better. Default is 64. (Doesn't include the prefix length)

defaultPrefix string

The prefix of the API key.

Note: We recommend you append an underscore to the prefix to make the prefix more identifiable. (eg hello_)

maximumPrefixLength number

The maximum length of the prefix.

minimumPrefixLength number

The minimum length of the prefix.

requireName boolean

Whether to require a name for the API key. Default is false.

maximumNameLength number

The maximum length of the name.

minimumNameLength number

The minimum length of the name.

enableMetadata boolean

Whether to enable metadata for an API key.

keyExpiration { defaultExpiresIn?: number | null; disableCustomExpiresTime?: boolean; minExpiresIn?: number; maxExpiresIn?: number; }

Customize the key expiration.

rateLimit { enabled?: boolean; timeWindow?: number; maxRequests?: number; }

Customize the rate-limiting.

schema InferOptionSchema<ReturnType<typeof apiKeySchema>>

Custom schema for the API key plugin.

enableSessionForAPIKeys boolean

An API Key can represent a valid session, so we can mock a session for the user if we find a valid API key in the request headers. Default is false.

storage "database" | "secondary-storage"

Storage backend for API keys. Default is "database".

• "database": Store API keys in the database adapter (default)
• "secondary-storage": Store API keys in the configured secondary storage (e.g., Redis)

fallbackToDatabase boolean

When storage is "secondary-storage", enable fallback to database if key is not found in secondary storage. Default is false.

export const auth = betterAuth({
  secondaryStorage: {
    get: async (key) => {
      return await redis.get(key);
    },
    set: async (key, value, ttl) => {
      if (ttl) await redis.set(key, value, { EX: ttl });
      else await redis.set(key, value);
    },
    delete: async (key) => {
      await redis.del(key);
    },
  },
  plugins: [
    apiKey({
      storage: "secondary-storage",
    }),
  ],
});

customStorage { get: (key: string) => Promise<unknown> | unknown; set: (key: string, value: string, ttl?: number) => Promise<void | null | unknown> | void; delete: (key: string) => Promise<void | null | string> | void; }

Custom storage methods for API keys. If provided, these methods will be used instead of ctx.context.secondaryStorage. Custom methods take precedence over global secondary storage.

Useful when you want to use a different storage backend specifically for API keys, or when you need custom logic for storage operations.

export const auth = betterAuth({
  plugins: [
    apiKey({
      storage: "secondary-storage",
      customStorage: {
        get: async (key) => await customStorage.get(key),
        set: async (key, value, ttl) => await customStorage.set(key, value, ttl),
        delete: async (key) => await customStorage.delete(key), 
      },
    }),
  ],
});

permissions { defaultPermissions?: Statements | ((userId: string, ctx: GenericEndpointContext) => Statements | Promise<Statements>) }

Permissions for the API key.

Read more about permissions here.

disableKeyHashing boolean

Disable hashing of the API key.

⚠️ Security Warning: It's strongly recommended to not disable hashing. Storing API keys in plaintext makes them vulnerable to database breaches, potentially exposing all your users' API keys.

Permissions

API keys can have permissions associated with them, allowing you to control access at a granular level. Permissions are structured as a record of resource types to arrays of allowed actions.

Setting Default Permissions

You can configure default permissions that will be applied to all newly created API keys:

export const auth = betterAuth({
  plugins: [
    apiKey({
      permissions: {
        defaultPermissions: {
          files: ["read"],
          users: ["read"],
        },
      },
    }),
  ],
});

You can also provide a function that returns permissions dynamically:

export const auth = betterAuth({
  plugins: [
    apiKey({
      permissions: {
        defaultPermissions: async (userId, ctx) => {
          // Fetch user role or other data to determine permissions
          return {
            files: ["read"],
            users: ["read"],
          };
        },
      },
    }),
  ],
});

Creating API Keys with Permissions

When creating an API key, you can specify custom permissions:

const apiKey = await auth.api.createApiKey({
  body: {
    name: "My API Key",
    permissions: {
      files: ["read", "write"],
      users: ["read"],
    },
    userId: "userId",
  },
});

Verifying API Keys with Required Permissions

When verifying an API key, you can check if it has the required permissions:

const result = await auth.api.verifyApiKey({
  body: {
    key: "your_api_key_here",
    permissions: {
      files: ["read"],
    },
  },
});

if (result.valid) {
  // API key is valid and has the required permissions
} else {
  // API key is invalid or doesn't have the required permissions
}

Updating API Key Permissions

You can update the permissions of an existing API key:

const apiKey = await auth.api.updateApiKey({
  body: {
    keyId: existingApiKeyId,
    permissions: {
      files: ["read", "write", "delete"],
      users: ["read", "write"],
    },
  },
  headers: user_headers,
});

Permissions Structure

Permissions follow a resource-based structure:

type Permissions = {
  [resourceType: string]: string[];
};

// Example:
const permissions = {
  files: ["read", "write", "delete"],
  users: ["read"],
  projects: ["read", "write"],
};

When verifying an API key, all required permissions must be present in the API key's permissions for validation to succeed.

Schema

Table: apiKey