Authentication

Every request (other than the embeddable widget's own endpoint) authenticates one of two ways: a first-party JWT (your users signing in through your own front end) or an API key (server-to-server integrations). Both resolve to the same RequestContext — a tenant id, and either a membership or an API key's own permission subset — so every endpoint behaves identically regardless of which one called it.

First-party JWT flow#

Institflow is multi-tenant: one user account can hold memberships in several institutes, so signing in is a three-step handshake rather than a single call.

1. POST /api/v1/auth/login with email, password, and client ("web" or "mobile"). The response carries a short-lived accessToken, the signed-in user, and every active membership the account holds. If there is exactly one, activeTenantId is already set and you can skip step 2.
2. POST /api/v1/auth/select-tenant with the chosen membershipId — returns a new accessToken scoped to that tenant. Every subsequent request's tenant context comes from this token, never from a header or query parameter you set yourself.
3. POST /api/v1/auth/refresh rotates the refresh token and issues a fresh accessToken before the old one expires. A refresh token that gets presented twice (reuse — a strong signal it was stolen) revokes the whole session family immediately (SESSION_REVOKED); sign in again.

Send the access token as Authorization: Bearer <accessToken> on every request. GET /api/v1/auth/me returns the current user, their memberships, and their effective permission list for the active tenant — useful for building your own session UI without re-deriving permissions client-side.

Secret API keys#

For server-to-server integrations (a script, a backend job, a partner system) create a secret key instead: POST /api/v1/api-keys (requires integration.manage) with a name and a permissions array — a strict subset of your own effective permissions; you can never grant a key more than you yourself hold. The full key (ifl_live_<32 random bytes, base64url>) is returned exactly once, at creation — only its prefix and a hash are ever stored, so if you lose it, revoke it and create a new one.

Authorization: Bearer ifl_live_9c1f2e7a4b8d3c6f0a5e9b2d7c4f1a8e

A key is bound to the tenant of the membership that created it and carries only its own permissions — not your full effective set — on every request it authenticates. Revoking a key (DELETE /api/v1/api-keys/:id) takes effect immediately, not after a cache expires.

Publishable keys#

A second key kind, ifl_pub_<…>, is safe to embed in front-end code — it can only call the /api/v1/public/* surface: POST /public/registrations (the endpoint the registration widget uses), POST /public/leads (contact-form enquiries), and the read-only course catalogue (GET /public/courses, /public/courses/:id, /public/branches — these answer 404 until the institute switches the public catalogue on). It is sent as X-Api-Key, is restricted to an explicit origin allowlist you configure per key, carries no staff permissions, and is rate-limited per IP and per key. Never use a publishable key for anything else — it deliberately cannot do anything else.

Idempotency-Key#

Every POST/PUT/PATCH/DELETE made with an API key must carry an Idempotency-Key header (any unique string — a UUID is the usual choice). First-party JWT callers may send one too, but it is optional for them.

• Missing on a key-authenticated mutation → 428 IDEMPOTENCY_KEY_REQUIRED.
• Same key, same method/path/body as before → the original response is replayed byte-for-byte (no re-execution — safe to retry a timed-out request blind).
• Same key, a different method/path/body → 409 IDEMPOTENCY_KEY_REUSED — you reused a key for a different request.
• Same key, arriving while the first request is still running → 409 IDEMPOTENCY_KEY_REUSED. The mutation runs once; retry after the first call returns.
• A 4xx is remembered too — a deterministic failure replays rather than re-running. A 5xx is never cached: retrying it really does re-execute, which is what you want after a server-side failure.

Keys are remembered for 24 hours.

Rate limits#

Every request is rate-limited by a Redis fixed window — per IP when unauthenticated, per user for JWT callers, per key for API-key callers (600 requests/minute by default). A key can be given its own narrower budget with rateLimitPerMin on POST /api/v1/api-keys or PATCH /api/v1/api-keys/{id} — useful for a key you hand to a third party. It can never be wider than your plan's ceiling; asking for more is a 422. Every response carries the current window's state, and RateLimit-Limit is always that key's own effective budget:

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 42

Exceeding the limit returns 429 with error code RATE_LIMITED — back off until RateLimit-Reset seconds have elapsed.