options fields

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

enableSessionForAPIKeys option enables mock sessions from API keys

When enableSessionForAPIKeys is enabled, any endpoint in Better Auth called with a valid API key in headers automatically creates a mock session representing the user. This feature only works with user-owned API keys (references: "user"), not organization-owned keys. When enabled, the API key is validated once per request and rate limiting is applied accordingly, avoiding double increment if manually verifying the key separately.

enableSessionForAPIKeys security warning

Using enableSessionForAPIKeys is generally not recommended because a leaked API key can be used to impersonate a user.

apiKeyHeaders option configures API key header names

The apiKeyHeaders option allows you to customize which headers are checked for API keys. The default header key is 'x-api-key', but this can be changed by setting apiKeyHeaders to an array of header names (e.g., ["x-api-key", "xyz-api-key"]) or a single string.

customAPIKeyGetter option for custom API key extraction

The customAPIKeyGetter option accepts a function that receives HookEndpointContext and returns the API key string or null if the request is invalid. This allows custom logic to extract the API key from requests beyond standard headers.

Multiple API key configurations with configId

You can define multiple API key configurations with different settings by passing an array of configuration objects to the apiKey plugin. Each configuration is identified by a unique configId and can have its own prefix, rate limits, permissions, and other options. This is useful for public vs private keys, read-only vs read-write keys, or different rate limits for different tiers.

Global options as second argument to apiKey plugin

The apiKey plugin accepts global options like schema as a second argument when using multiple configurations: apiKey([{ configId: "public", defaultPrefix: "pk_" }, ...], { schema: { ... } }).

references option configures API key ownership (user vs organization)

The references option in API key configuration determines ownership type. Set references: "user" (default) for user-owned keys or references: "organization" for organization-owned keys.

storage option set to "database" (default)

The storage: "database" option stores API keys only in the database adapter. This is the default mode and requires no additional configuration.

storage option set to "secondary-storage"

The storage: "secondary-storage" option stores API keys only in secondary storage (e.g., Redis) with no fallback to database. This is best for high-performance scenarios where all keys are migrated to secondary storage.

Secondary storage with fallbackToDatabase option

Setting storage: "secondary-storage" with fallbackToDatabase: true checks secondary storage first, then falls back to database if not found. On read, it automatically populates secondary storage when falling back (cache warming). On write, it writes to both database and secondary storage to ensure consistency.

customStorage option for API key-specific storage

The customStorage option allows custom storage methods specifically for API keys, overriding global secondaryStorage configuration. It accepts get, set, and delete async functions with signatures: get(key), set(key, value, ttl), and delete(key).

rateLimit option structure for API keys

The rateLimit option has three fields: enabled (boolean), timeWindow (milliseconds), and maxRequests (number). Example: { enabled: true, timeWindow: 1000 * 60 * 60, maxRequests: 100 } for 100 requests per hour.

customKeyGenerator option for custom key generation

The customKeyGenerator option accepts a function receiving { length, prefix } and returning a custom API key string. Allows overriding default key generation logic with custom implementations.

customAPIKeyValidator option for custom verification

The customAPIKeyValidator option accepts an async function receiving { ctx, key } and returning a boolean indicating validity. This allows improving API key verification performance by invalidating failed keys without querying the database.

defaultKeyLength required for custom key generators not using length parameter

If the customKeyGenerator function does not use the length property parameter, the defaultKeyLength property must be set to specify the length of generated keys.

enableMetadata option enables metadata storage for API keys

Set enableMetadata: true in plugin options to enable storing metadata alongside API keys. This is useful for storing information about the key such as subscription plan.

Give your agent this brain