API Key

The ApiKeyPlugin provides API key management with support for rate limiting, usage quotas, expiration, and permissions.

Setup

These examples assume you've already defined AppAuthSchema. If you want a complete setup from entity definitions through Axum mounting, start with the Axum integration guide.

use better_auth::plugins::ApiKeyPlugin;

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(ApiKeyPlugin::new())
    .build()
    .await?;

Configuration

use better_auth::plugins::api_key::{ApiKeyConfig, RateLimitDefaults, KeyExpirationConfig};

let auth = BetterAuth::<AppAuthSchema>::new(config)
    .store(store)
    .plugin(
        ApiKeyPlugin::builder()
            .key_length(64)
            .prefix("sk_".to_string())
            .enable_metadata(true)
            .build()
    )
    .build()
    .await?;

How It Works

Key Generation

API keys are generated as random alphabetic strings ([a-zA-Z]) of the configured length. The key format is:

{prefix}{random_alpha_chars}

Only the SHA-256 hash of the key is stored in the database. The full key is returned only once during creation and cannot be retrieved later.

Key Structure

Each API key has:

• start: First 6 characters of the full key including prefix (for UI identification)
• prefix: Optional prefix (e.g., sk_, pk_)
• enabled: Whether the key is active
• remaining: Usage quota (decremented on each use, null = unlimited)
• expiresAt: Optional expiration date (set via expiresIn in seconds)
• Rate limiting: Counter-based rate limits with configurable time window and max requests

API Endpoints

The API Key plugin exposes 5 client-facing endpoints. All require an authenticated session.

Errors