API keys

Your project includes API key management for programmatic access to the REST API. API keys are scoped to an organization and can have granular permissions and expiration dates.

How it works

1. User creates an API key from the /api-key page.
2. The key is generated via Better Auth's API key plugin and displayed once.
3. External clients authenticate by passing the key in the x-api-key header.
4. Each API call made with the key is logged in the audit log with the HTTP method, endpoint, and response code.

Creating an API key

Navigate to /api-key and click New. You can configure:

• Name: A descriptive label for the key (required, max 255 characters).
• Expiration: Optional expiry time in seconds.
• Permissions: Optional granular permissions. The key can only have permissions that the creating user already has.

Important: The full API key is shown only once at creation time. Copy it immediately — it cannot be retrieved later.

Using an API key

Pass the key in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" \
     https://your-backend-url/api/your-entity

Alternatively, you can use Bearer authentication:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://your-backend-url/api/your-entity

Managing API keys

From the API key list page you can:

• View all keys with their name, status, and creation date.
• Edit a key's name or enable/disable it.
• Delete a key permanently.

Disabled keys return a 401 error when used.

Audit logging

Every API call made with an API key is automatically logged in the audit log with:

• The HTTP method (GET, POST, PUT, DELETE)
• The API endpoint path
• The HTTP response code

This provides a complete audit trail of all programmatic access.

Permissions

API key management requires the apiKey permission resource:

Both admin and member roles have these permissions by default.

API endpoints

Key files