API keys - BabySea Docs

API keys authenticate all BabySea public /v1 requests via the Authorization: Bearer <token> header. Manage them in the API keys section of the console.

curl https://api.<your_region>.babysea.ai/v1/status \
  -H "Authorization: Bearer bye_your_api_key"

Access control

In a personal workspace, the sole owner manages all keys. In team workspaces, RBAC applies:

Role	Access
`primary-owner` / `owner`	Provision, rotate, revoke, and delete keys
`member`	Read-only — view metadata and audit logs only

Key format and storage

Keys use the bye_ prefix followed by a Base64-encoded random value:

bye_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9

BabySea stores only the first 9 characters (the prefix) and a one-way cryptographic hash. The raw key is never stored and is shown exactly once — at creation or rotation.

Store the key in your secrets manager before closing the dialog. It cannot be retrieved afterward.

Authentication flow

For every /v1 request, BabySea runs these checks in order:

Read the bearer token

Accepts Authorization: Bearer bye_... header.

Identify the key

Uses the key prefix to locate the key record.

Verify the key

Validates the cryptographic hash against the presented secret.

Check lifecycle state

Inactive or expired keys fail immediately.

Check the IP allowlist

If configured, rejects requests from unlisted IPs with BSE1007.

Check route scope

Verifies the key has the required scope for the requested endpoint.

All checks pass → request reaches the route handler.

Key status

Status	Authenticates	Meaning
`Active`	Yes	Key is live and valid
`Rotated`	Yes (until grace period ends)	Old key within its overlap window
`Expired`	No	Expiration timestamp reached
`Revoked`	No	Manually disabled

The grace period (1–168 hours, default 24h) is the overlap window after rotation where both old and new keys work.

Permission presets

Scopes are bound to a key at creation and cannot be changed. Choose the most restrictive preset your workload requires.

Preset	Scopes granted	Best for
`Full Access`	All — read, write, delete	Production API servers
`Generate Only`	`generation:write`, `generation:read`, `library:read`	Background workers that only start generations
`Read Only`	`generation:read`, `account:read`, `health:read`, `library:read`	Dashboards, usage readers
`Monitor Only`	`health:read`, `library:read`	Uptime monitors, catalog browsers

Scope → endpoint mapping

Scope	Endpoints
`generation:write`	`POST /v1/generate/image/{model}`, `POST /v1/generate/video/{model}`
`generation:read`	`GET /v1/content/{id}`, `GET /v1/content/list`
`generation:delete`	`DELETE /v1/content/{id}`, `POST /v1/content/generation/cancel/{id}`
`account:read`	`GET /v1/user/account`, `GET /v1/user/billing`, `GET /v1/usage`, `GET /v1/status`
`health:read`	`GET /v1/health/inference/providers`, `GET /v1/health/inference/models`, `GET /v1/health/storage`, `GET /v1/health/cache`
`library:read`	`GET /v1/library/providers`, `GET /v1/library/models`, `GET /v1/estimate/{model}`

To change scopes, provision a new key with the desired preset, migrate your applications, then revoke the old key.

Create a key

Requires: primary-owner or owner role.

Open API keys

Navigate to API keys in the console sidebar.

Provision a new key

Click Create API key.

Enter a name

Up to 100 characters. Use descriptive names tied to the workload:

Example	Use case
`prod-api-worker`	Production image generation backend
`dev-frontend`	Local development
`staging-monitor`	Staging health checks
`analytics-reader`	Usage dashboard

Choose a permission preset

Select a preset. Defaults to Full Access. Scopes are immutable after creation.

Optional — add an IP allowlist

Enter comma-separated IPs (max 50 entries, 45 chars each). Leave empty to allow all IPs.

203.0.113.10, 198.51.100.5, 2001:db8::1

Click Add

The button is disabled until a valid name is entered.

Store the key

BabySea shows the full key exactly once. Copy it to your secrets manager before closing.

bye_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9

Using your key

SDK
cURL
Python

TypeScript

import { BabySea } from 'babysea';

const client = new BabySea({
  apiKey: process.env.BABYSEA_API_KEY,
  region: 'us',
});

const result = await client.generate('bfl/flux-schnell', {
  generation_prompt: 'A baby seal plays in Arctic',
});

Terminal

curl -X POST https://api.<your_region>.babysea.ai/v1/generate/image/bfl/flux-schnell \
  -H "Authorization: Bearer bye_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"generation_prompt": "A baby seal plays in Arctic"}'

Python

import requests

response = requests.post(
    "https://api.<your_region>.babysea.ai/v1/generate/image/bfl/flux-schnell",
    headers={
        "Authorization": "Bearer bye_your_api_key",
        "Content-Type": "application/json",
    },
    json={"generation_prompt": "A baby seal plays in Arctic"},
)
print(response.json())

Verify the key

Terminal

curl https://api.<your_region>.babysea.ai/v1/status \
  -H "Authorization: Bearer bye_your_api_key"

Requires account:read — available on Full Access and Read Only. For Generate Only keys, send a generation request instead.

Store it securely

.env

BABYSEA_API_KEY=bye_your_api_key

Never commit API keys to version control, embed them in client-side code, or share them in plaintext.

IP allowlist

Restrict a key to specific egress IPs. Requests from unlisted IPs are rejected with BSE1007 before reaching any route handler. Allowlists are immutable after creation — to update, provision a new key with the revised list, migrate, then revoke the old one.

Rule	Detail
Match type	Exact string match
Max entries	50 IPs per key
Max length per IP	45 characters
Empty	All IPs allowed
Inherited on rotation	Yes
Raw IP logged	Never — SHA-256 hash only

Common setups

Single server

203.0.113.10

Multiple servers / load balancer

203.0.113.10, 203.0.113.11, 203.0.113.12

For serverless or dynamic egress environments, omit the allowlist and enforce least-privilege scopes instead.

Combine IP allowlists with the narrowest possible scope preset for defense in depth.

Rotation, revocation, and deletion

Rotate

Rotation replaces a key while keeping the old one active during a configurable grace period (1–168 hours, default 24h), so you can update applications without downtime.

Open rotation

In the API keys table, open the three-dot menu and select Rotate.

Choose a grace period

Options: 1h, 6h, 12h, 24h (default), 48h, 72h, 168h.

Store the new key

BabySea shows the new key once. Copy it before closing the dialog.

Deploy the new key

Update your secrets manager and redeploy your services.

Grace period expires

The old key stops authenticating automatically. No action needed.

The replacement key inherits the original’s name, scopes, and IP allowlist. Scopes are still immutable. Example quarterly rotation (default 24h grace):

Mon 10:00 — Rotate prod-api-worker, copy new key
Mon 10:05 — Update secrets manager
Mon 10:10 — Deploy; services pick up new key
Mon 10:30 — Verify with GET /v1/status
Tue 10:00 — Grace period expires; old key stops working

Set a reminder before the grace period ends to confirm all services are on the new key.

Rotate vs. revoke

Action	Old key	New key	Use when
Rotate	Active during grace period	Yes	Planned refresh
Revoke	Disabled immediately	No	Key is compromised or leaked

If a key is compromised — revoke, don’t rotate.

Revoke

Revocation immediately disables the key. All requests return BSE1002 from that moment. The key and its logs remain visible in the table but the key cannot be reactivated.

Revocation is irreversible. To restore access, create a new key.

Delete

Deleting permanently removes the key and all associated request logs. The key is also immediately revoked if still active. Aggregate daily statistics are preserved in account analytics before deletion.

If you still need the audit logs, revoke instead of deleting. Deletion removes individual log entries permanently.

Action availability

Action	Active	Rotated	Expired	Revoked
Rotate	✓	—	—	—
Revoke	✓	✓	—	—
Delete	✓	✓	✓	✓

Usage tracking

BabySea records a Last used timestamp on every authenticated request. Keys that have never been used display No activity. Request metadata (endpoint, method, status code, SHA-256 hash of client IP) is logged for auditing. Raw IPs are never stored.

Error reference

Code	Type	Message	HTTP
`BSE1001`	`missing_api_key`	Missing API key. Provide a valid key via the Authorization header.	401
`BSE1002`	`invalid_api_key`	Invalid or expired API key.	401
`BSE1003`	`insufficient_permissions`	API key does not have permission for this resource.	403
`BSE1007`	`ip_not_allowed`	This IP address is not in the allowlist for this API key.	403

All errors include "retryable": false. To resolve BSE1003, provision a new key with a preset that includes the required scope.

Dashboard

Setup

​Access control

​Key format and storage

​Authentication flow

​Key status

​Permission presets

​Scope → endpoint mapping

​Create a key

​Using your key

​Verify the key

​Store it securely

​IP allowlist

​Common setups

​Rotation, revocation, and deletion

​Rotate

​Rotate vs. revoke

​Revoke

​Delete

​Action availability

​Usage tracking

​Error reference

Access control

Key format and storage

Authentication flow

Key status

Permission presets

Scope → endpoint mapping

Create a key

Using your key

Verify the key

Store it securely

IP allowlist

Common setups

Rotation, revocation, and deletion

Rotate

Rotate vs. revoke

Revoke

Delete

Action availability

Usage tracking

Error reference