Skip to main content

​
What are scopes?

Scopes define which /v1 endpoints an API key can call. In the dashboard, you choose a permission preset. BabySea then converts that preset into the route permissions enforced by the API. When a key lacks the required scope for an endpoint, BabySea returns BSE1003.

​
Scope presets

When you create a key, the Permissions section shows these four presets:

​
Full Access

Dashboard description: All permissions - read, write, delete
ScopeIncluded
generation:writeYes
generation:readYes
generation:deleteYes
account:readYes
health:readYes
library:readYes

​
Generate Only

Dashboard description: Create & read generations + browse models
ScopeIncluded
generation:writeYes
generation:readYes
generation:deleteNo
account:readNo
health:readNo
library:readYes

​
Read Only

Dashboard description: Read generations, account info, health - no spending
ScopeIncluded
generation:writeNo
generation:readYes
generation:deleteNo
account:readYes
health:readYes
library:readYes

​
Monitor Only

Dashboard description: Health checks & model catalog - no account data
ScopeIncluded
generation:writeNo
generation:readNo
generation:deleteNo
account:readNo
health:readYes
library:readYes

​
Scope reference

Each scope maps to one or more API endpoints. Below is the complete mapping.

​
generation:write

Create new image and video generations.
MethodEndpoint
POST/v1/generate/image/{model_identifier}
POST/v1/generate/video/{model_identifier}

​
generation:read

Retrieve generation records and generation history.
MethodEndpoint
GET/v1/content/{generation_id}
GET/v1/content/list

​
generation:delete

Cancel in-progress generations and delete stored generation records.
MethodEndpoint
DELETE/v1/content/{generation_id}
POST/v1/content/generation/cancel/{generation_id}

​
account:read

Access account information, billing information, usage data, and key status checks.
MethodEndpoint
GET/v1/user/account
GET/v1/user/billing
GET/v1/usage
GET/v1/status

​
health:read

Check the health of inference providers, models, storage, and cache.
MethodEndpoint
GET/v1/health/inference/providers
GET/v1/health/inference/models
GET/v1/health/storage
GET/v1/health/cache

​
library:read

Browse the model and provider catalog, and request cost estimates.
MethodEndpoint
GET/v1/library/providers
GET/v1/library/models
GET/v1/estimate/{model_identifier}

​
Choosing the right preset

Use caseRecommended preset
Production API serverFull Access
Background workerGenerate Only
Internal analytics dashboardRead Only
Uptime monitoring serviceMonitor Only
CI/CD pipeline testingGenerate Only
Client side status widgetMonitor Only
Cost estimation toolRead Only
Start with the smallest preset that works for your application.

​
Change management

The current dashboard does not provide an edit action for key scopes. If you need different permissions:
  1. Create a new key with the correct preset.
  2. Update your application to use the new key.
  3. Revoke or delete the old key when you are finished.
Rotation does not change scopes. It creates a replacement key with the same permissions as the original key.

​
Scope errors

When a key attempts to access an endpoint outside its permissions:
JSON
{
  "status": "error",
  "request_id": "req_a1b2c3d4",
  "error": {
    "code": "BSE1003",
    "type": "insufficient_permissions",
    "message": "API key does not have permission for this resource.",
    "retryable": false
  }
}
To resolve this error, create a new key with a preset that includes the required scope, or delete and recreate the existing key with broader permissions.
Scopes are set when the key is created. To use different scopes, create another key.