API Keys

API keys allow organizations to authenticate programmatic access to the API. Each key is scoped to an organization, hashed for security, and supports fine-grained permissions and rate limits.

ApiKey Model

The ApiKey model stores all key metadata. The actual key value is never stored — only a SHA-256 hash.

• organization_id — the organization this key belongs to
• created_by — the user who created the key
• name — a human-readable label (e.g. "Production API")
• key_hash — SHA-256 hash of the full key
• key_prefix — first 8 characters of the key for identification
• permissions — JSON array of granted scopes
• rate_limit_per_minute — per-key rate limit (default from plan)
• last_used_at — timestamp of the last authenticated request
• expires_at — optional expiration date

Endpoints

List API Keys

GET /api/api-keys

Returns all API keys for the current organization. The key value is never returned — only the prefix, name, permissions, and metadata.

Create API Key

POST /api/api-keys

{
    "name": "Production API",
    "permissions": ["read", "write"],
    "rate_limit_per_minute": 60,
    "expires_at": "2026-12-31T23:59:59Z"
}

Returns the plain-text key once in the response. The key format is lk_ followed by 40 random characters:

{
    "key": "lk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
    "api_key": { "id": 1, "name": "Production API", "..." }
}

Important: The plain-text key cannot be retrieved again. If lost, the key must be revoked and a new one created.

Revoke API Key

DELETE /api/api-keys/{id}

Permanently revokes the key. All future requests using this key will be rejected.

List Available Scopes

GET /api/api-keys/scopes

Returns all available permission scopes, including core scopes and any custom scopes defined in config/custom.php.

Authentication Middleware

The AuthenticateApiKey middleware handles API key authentication on protected routes:

• Extracts the key from the Authorization: Bearer lk_... header
• Computes the SHA-256 hash and looks up the matching ApiKey record
• Validates that the key has not expired (expires_at check)
• Verifies that the key's organization is still active
• Updates last_used_at timestamp

Notifications

When a new API key is created:

• An ApiKeyCreatedNotification is sent to the user who created it
• A webhook event api_key.created is dispatched to the organization's registered webhooks