Public API

A REST API for third-party integrations. It authenticates with API keys, is hard-scoped to one institution per key, enforces per-endpoint scopes, and returns a consistent JSON envelope.

Base URL: https://<project-ref>.supabase.co/functions/v1/api-v1Spec: docs/api/openapi.yaml in the repository (OpenAPI 3.1)

Authentication

Mint a key under API Access in the dashboard. The secret (sk_live_…) is shown once.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

x-api-key: sk_live_… is also accepted.

• Institution keys only ever read and write their own institution's data. Isolation is enforced by the gateway, independently of row-level security.
• Platform keys (super admin only) span institutions: pass ?tenant_id= on lists and tenant_id in write bodies.

Scopes

Scope domain	Resources
students	/students
academics	/classes, /enrollments, /subjects, /academic-years
attendance	/attendance
exams	/exams, /exam-marks
finance	/fee-records
wallet	/wallet-transactions (read), /students/{id}/wallet (write)
store	/store-products, /store-orders

GET needs <domain>:read, and POST/PATCH/DELETE need <domain>:write. <domain>:* grants both, and * grants everything.

Responses

{ "data": { } }                                              // one record
{ "data": [ ], "meta": { "total": 128, "limit": 50, "offset": 0 } }   // a list
{ "error": { "code": "insufficient_balance", "message": "…" } }        // an error

Status	Meaning
200 / 201 / 204	OK / created / deleted
400	Validation
401	Missing or bad key
403	Scope or institution not allowed
404 / 405	Not found / method not allowed
409	Business conflict (e.g. insufficient balance)
429	Rate limited: 600 requests per minute per key