Management API

The Management API (/v1/*) is the control plane the dashboard itself uses. Anything you can click in the dashboard, you can script. A machine-readable OpenAPI 3.1 spec is available at GET /v1/openapi.json.

Authenticate with a personal access token

1. Sign in to the dashboard.
2. Open Account → Access tokens and create a personal access token (PAT) with the scopes you need. The token (lb_pat_...) is shown once. Tokens can expire and be revoked.
3. Send it as a bearer token.

Scope	Allows
projects:read / projects:write	projects, keys, config, webhooks, secrets, backups
database:read / database:write	tables, policies, migrations, SQL, extensions, advisors
auth:admin	project users, providers, tenants
org:admin	organizations and members

A write scope implies the matching read scope. org:<uuid> and project:<ref> entries restrict a token to those resources. A PAT can never create or revoke PATs.

export BASE_API=https://<management-api-url>
export PAT=lb_pat_...
curl -s -H "Authorization: Bearer $PAT" $BASE_API/v1/projects

Recipes

Create a project and wait until it is active:

curl -s -X POST -H "Authorization: Bearer $PAT" -H 'content-type: application/json' \
  -d '{"organization_id":"<org uuid>","name":"Shop","ref":"shop"}' $BASE_API/v1/projects   # 201, status "provisioning"
curl -s -H "Authorization: Bearer $PAT" $BASE_API/v1/projects/shop   # poll until status is "active"

Apply a migration from CI (idempotent: replaying the same version and checksum returns 200):

jq -n --arg sql "$(cat potalab/migrations/20260929120000_create_todos.sql)" \
      '{name:"20260929120000_create_todos", sql:$sql}' |
curl -s -X POST -H "Authorization: Bearer $PAT" -H 'content-type: application/json' -d @- \
  $BASE_API/v1/projects/shop/database/migrations

Generate an owner-only policy (preview first with ?dry_run=true):

curl -s -X POST -H "Authorization: Bearer $PAT" -H 'content-type: application/json' \
  -d '{"table":"public.todos","command":"all","mode":"owner","owner_column":"owner_id"}' \
  "$BASE_API/v1/projects/shop/database/policies?dry_run=true"

Task	Request
Enable realtime	PATCH /v1/projects/shop/config/realtime {"enabled":true,"tables":["public.todos"]}
Create a secret key (shown once)	POST /v1/projects/shop/api-keys {"kind":"secret","name":"backend"}
Run the security advisor	GET /v1/projects/shop/advisors
See plan features	GET /v1/projects/shop/features
Tune rate limits (owner)	PATCH /v1/projects/shop/config/rate-limits {"user":{"rps":30}}

Behavior to rely on

• Roles: viewer is read-only; developer manages schema, policies, config and webhooks; owner also manages keys, secrets, SMTP, rate limits, the audit log, backups and project deletion. A non-member gets 404, not 403.
• Audit: every write is recorded, including denied attempts. Owners read it with GET .../audit-log.
• Config changes propagate to the data, auth and realtime services in about a second.
• Rate limit: 600 requests per minute per IP. Honor Retry-After on 429.
• Plan gating: writes that need a feature outside your plan answer 402 feature_not_in_plan; limits answer 402 plan_limit_exceeded. See Plans and limits.
• During a restore the project is in maintenance and project routes answer 503 project_maintenance with Retry-After.

Direct database connection strings and type generation over the API are not available yet; use potalab base gen types from the CLI.