← Kuunda Docs
Console

Remote SQL migrations

To apply controlled DDL or DML on the tenant schema without opening the console (CI, codegen, agents), Kuunda exposes an endpoint on the dashboard app (not on the REST gateway). Authentication is the project service_role key only.

Endpoint

  • Method : POST
  • URL : {origine_dashboard}/api/projects/{ref8}/migrate/service-role
  • In production the dashboard origin is often https://app.kuunda-cloud.com (variable NEXT_PUBLIC_APP_URL in this doc).
  • The ref8 in the URL must match the project bound to the key (otherwise 403).

Authentication

Header apikey or Authorization: Bearer with the project service_role key. The anon key is rejected (service_role_required).

Request body

JSON:

{ "sql": "CREATE TABLE …" }

Size limits and SQL filters match the console SQL editor (monorepo guards: tenant-migration-sql-guards). Project schema only (no public. prefix); JWT identity via auth.uid() / auth.email() / auth.role() / auth.jwt(), no Auth catalog reads.

cURL example

Replace abcdef12 with your project ref and the key with your service_role.

curl -sS -X POST "https://app.kuunda-cloud.com/api/projects/abcdef12/migrate/service-role" \
  -H "Content-Type: application/json" \
  -H "apikey: <YOUR_SERVICE_ROLE_KEY>" \
  -d '{"sql":"CREATE TABLE example (id uuid PRIMARY KEY DEFAULT gen_random_uuid());"}'

Security

  • Never expose the service_role key in the front end or a public repository.
  • Prefer calls from the server (CI, backend, agent with a managed secret).
  • Successful JSON response: same shape as the console query/migrate route (ok, rowCount, etc.).

See also

  • Console: Settings → API: “Remote SQL migrations” block with the URL and example for your project.
  • API technical entry (gateway) : REST API, not migrations.
  • SDK: packages/kuunda-js/README.md (migrations section).