Skip to main content
Scopes define which public /v1 routes an API key can call. In the dashboard, you choose a preset in the Permissions section. BabySea converts that preset into the route permissions enforced by each handler. When a key reaches a route without the required scope, BabySea returns BSE1003.

​
Presets in Add API key

The Permissions section currently shows 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 public /v1 endpoints.

​
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 worker that only starts generationsGenerate Only
Application that reads usage or account dataRead Only
Provider or storage uptime monitorMonitor Only
Model catalog browser or estimation toolMonitor Only
Start with the smallest preset that works for your application.

​
Change management

The current dashboard does not provide an edit action for 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.