Getting started

Intervengine is a platform for keeping something small in front of a person every day between appointments, and acting on what they say. Participants use an app on their phone; staff work in a portal; both, and anything you build, use the same API.

This site explains how the platform works: what each domain is for, how they depend on each other, and the rules behind the fields. Every operation, field and status code is in the API reference, linked at the top of every page. Guides, tutorials and worked examples are at guide.intervengine.com.

What you need

A tenant (your organisation's space on the platform), a user in it with a staff role, and the address of your deployment's API host. Everything you call lives under /api/v1/ on that host.

Two ways in

As a person. A user signs in through the identity provider and receives a session. Apps and your own code send it as a bearer token; the portal holds it in a cookie. Whatever the signed-in user's role allows, the call is allowed. Authentication walks through signing in from your own code.

As a system. A platform admin creates an API key for a service that calls the API on its own behalf. The service exchanges the key at the identity provider for an access token and sends that as a bearer token. The key acts as its own user in the tenant, and its role decides what it reaches.

Your first call

With a session token, ask the API who you are:

GET /api/v1/auth/sessions/current
Authorization: Bearer <token>

You get back the session: the user, their tenant and their role. (An API key is refused here; start with the list below.) Then list something the role can see:

GET /api/v1/cohorts?perPage=1
Authorization: Bearer <token>

{
  "data": [{ "id": "…", "code": "…", "name": "…" }],
  "meta": { "total": 3, "page": 1, "perPage": 1 }
}

That envelope, those query parameters and that error shape are the same on every resource; Conventions covers them once. How the platform fits together is the map of every domain.