Skip to main content

Overview

A user is a login identity — separate from a patient, which is the clinical record created with POST /patients. Steps 1-5 are a fixed sequence: create the identity, prove the patient owns the email you have on file, then hand them their own tokens — each step hands the next its input, so skipping one or calling them out of order fails. Every step runs on a service token except the token exchange, which authenticates with your client_id/client_secret in the body plus the verification_code — so it belongs on your backend, not in the client.
Not yet verified against staging (needs a user-token flow / a program-specific tenant). Treat field-level detail as indicative.
1

Obtain a service token

POST /auth/token with the client_credentials grant. Use this token as the Bearer credential for steps 2-4 — not for the verification-code exchange in step 5.audience is a fixed identifier, not the host you call, and differs by environment — see Obtain a service token for more details.
See Obtain a service token for the full parameter and response reference.
2

Register the identity

POST /auth/register creates the identity. It starts pending_verification and does not return tokens — there’s nothing to authenticate yet. The service token must carry the users:create permission.
201
See Register a user for the full reference.
3

Send a one-time code

POST /auth/send-otp emails a 6-digit code to the address from registration. It’s the same entry point used for returning-user login, so the response doesn’t reveal whether the email is registered. The service token must carry the otps:send permission.
See Send a one-time login/verification code for the full reference.
4

Verify the code

POST /auth/verify-otp redeems the 6-digit code for a short-lived verification_code (~60s). Success also flips the identity from pending_verification to active. The service token must carry the otps:verify permission.
See Verify a one-time code for the full reference.
When the code fails. A 403 here means the code was wrong, expired, or the caller has made too many attempts — the response’s reason field distinguishes invalid_code from too_many_attempts. There’s no separate “resend” endpoint: re-call POST /auth/send-otp from step 3 to issue a fresh code and restart the attempt count.
5

Exchange the verification code for user tokens

POST /auth/token again, now with the verification-code grant. This call carries no Bearer token — it authenticates with your client_id/client_secret in the body plus the verification_code, so it belongs on your backend, not in the client — and returns the user’s own access_token and refresh_token, nested under data.
See Exchange a verification code for the full reference.
From here the user authenticates with their own access_token, not the service token used in steps 2–4.

Keeping the session alive

Once a user holds tokens, don’t repeat the OTP flow to keep them signed in:
  • Refresh with POST /auth/token using the refresh_token grant, before expires_in elapses. See Refresh a token.
  • Revoke with POST /auth/revoke to end a session on logout. See Revoke a token.
  • Delete the account with DELETE /iam/users/me, sent with the user’s own token — there’s no id parameter, so a caller can only delete their own account. See Delete your account.

Obtain a service token

The client_credentials grant used in steps 2-4

API Reference

Endpoint details and schemas