API Key Scopes

Scopes define what an API key is allowed to do. Each key is assigned a set of permission scopes at creation time, and every request is checked against those scopes.

Core Scopes

These scopes are built into the system and available to all organizations:

• read — read access to general organization resources
• write — write access to general organization resources
• members:read — list and view organization members
• members:write — invite, remove, and change roles of members
• billing:read — view subscription, invoices, and billing info
• api_keys:read — list API keys
• api_keys:write — create and revoke API keys
• webhooks:read — list webhooks and view delivery history
• webhooks:write — create, update, and delete webhooks

Custom Scopes

Custom scopes are auto-generated from the permissions array in config/custom.php. Any permission you define there becomes available as an API key scope.

// config/custom.php
'permissions' => [
    'projects:read',
    'projects:write',
    'comments:read',
    'comments:write',
],

These scopes will appear alongside the core scopes when creating API keys via the UI or the GET /api/api-keys/scopes endpoint.

Scope Enforcement

Use the CheckApiKeyScope middleware to enforce scopes on individual routes:

Route::get('/projects', [ProjectController::class, 'index'])
    ->middleware('api_key.scope:read');

Route::post('/members', [MemberController::class, 'store'])
    ->middleware('api_key.scope:members:write');

If the API key does not have the required scope, a 403 Forbidden response is returned.

Multiple Scopes

You can require multiple scopes on a single route. The key must have all listed scopes:

Route::put('/projects/{id}', [ProjectController::class, 'update'])
    ->middleware('api_key.scope:read,write');