Overview
A user is a login identity — separate from a patient, which is the clinical record created withPOST /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.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
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.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.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.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/tokenusing therefresh_tokengrant, beforeexpires_inelapses. See Refresh a token. - Revoke with
POST /auth/revoketo 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 noidparameter, so a caller can only delete their own account. See Delete your account.
Related
Obtain a service token
The client_credentials grant used in steps 2-4
API Reference
Endpoint details and schemas

