Authentication

The Insito API has two authentication modes — one for SDK traffic from your mobile app, one for dashboard traffic from the admin.insito.app web UI. They never overlap.

SDK: project API keys

All /v1/sdk/* routes require a Bearer token in the Authorization header. The token is your project’s API key from admin.insito.app → your app → Settings → Mobile SDK.

POST /v1/sdk/event HTTP/1.1
Host: api.insito.app
Content-Type: application/json
Authorization: Bearer proj_0123456789abcdef0123456789abcdef

{ "event": "checkout_completed", "userId": "user-123" }

API keys:

Format: proj_ followed by a 32-character hex string (generated per project). The auth middleware accepts a proj_<alphanumeric> bearer token.
One key per project. Settings → Mobile SDK → Regenerate key creates a new key and invalidates the old one immediately.
The key binds every request to a single project, so all SDK traffic is automatically scoped to that project. A missing, malformed, or rotated key returns 401 unauthorized.

The project key is public, not a secret: it ships inside every build of your app and anyone can extract it. Abuse is bounded by per-key rate limits and your plan’s response quota. It only grants the SDK endpoints, never dashboard data. Still keep it out of public repos (pass it in at build time) so you can regenerate it without a code change.

Dashboard: Supabase JWTs

/v1/dashboard/* routes require a Supabase auth JWT in the same Authorization: Bearer shape.

GET /v1/dashboard/projects HTTP/1.1
Host: api.insito.app
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Get one by signing in via Supabase Auth against the same project the dashboard uses. The JWT is short-lived (1 hour by default) — refresh via the refresh token flow. Routes apply per-org RLS based on the JWT’s sub (user ID) and the members table. Cross-org access returns 404.

Rate limits

/v1/sdk/* routes use sliding one-minute windows in Upstash Redis:

120 requests per minute per API key per client IP, so one device or script can’t use up an app’s budget;
3,000 requests per minute per API key across all clients;
30 unknown API keys per minute per client IP. Past that, keys that aren’t already known return 429 instead of being looked up, which stops key guessing. Valid keys already in use from that IP keep working.

Exceeding a limit returns 429 with { "error": "too_many_requests" } and X-RateLimit-Limit / X-RateLimit-Remaining headers. There is no Retry-After header; the window is one minute. /v1/dashboard/* routes allow 300 requests per minute per signed-in user or API key. See Plan limits for response caps. Changes to an app (a regenerated key, deactivation, Brand Kit or labels) take effect on the SDK’s next request.

Error shape

Validation failures (Zod) return:

{
  "error": "bad_request",
  "issues": [{ "path": "userId", "message": "Required" }]
}

All other errors are a flat object with error plus any context fields at the top level (there is no details wrapper):

{ "error": "response_limit_reached", "upgradeUrl": "https://app.insito.io/settings/billing", "projectId": "<uuid>" }

Common codes:

Code	HTTP	Meaning
`unauthorized`	401	Missing, malformed, or rotated `Authorization` token
`not_found`	404	Resource doesn’t exist (or is in a different org — deliberately ambiguous)
`bad_request`	400	Body failed Zod validation; see the `issues` array
`conflict`	409	Unique constraint violation (e.g. duplicate key)
`too_many_requests`	429	SDK rate limit hit (120 req/min per key)
`response_limit_reached`	402	Plan exhausted; payload includes top-level `upgradeUrl` and `projectId`
`internal_error`	500	Bug on our end

Versioning

The API is versioned via URL prefix (/v1). We bump major versions for breaking changes; backwards-compatible additions never get a new version.