Patient registration

Creates a patient account in a tenant and signs the patient in straight away: the response carries tokens, so there is no separate sign-in step.

Method	Path
POST	/auth/tenant/Patient/register

No bearer token is needed. The tenant is named by tenantCode.

What the project needs

Registration is refused unless the project is set up for it. Check both before you build the screen.

Requirement	Detail
A default patient AccessPolicy	defaultPatientAccessPolicy on the project. Every new patient receives it, and registration is refused with 403 until it exists. There is no settings endpoint for it; see set up your project.
Registration switched on	PATIENT_REGISTRATION_ENABLED must not be false. It is on when unset, but GET /v1/project/settings reports false for a project that has never set it. Set it explicitly.

Request

curl --request POST \
  --url 'https://api.sandbox.ovok.com/auth/tenant/Patient/register' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "patient@example.com",
    "password": "your-password",
    "name": "Ada",
    "surname": "Lovelace",
    "tenantCode": "big-health-company"
  }'

Body field	Required	Description
email	Yes	The patient's email. Ovok lowercases it.
password	Yes	The patient's password. Enforce your own password rules in your app.
name	Yes	Given name.
surname	Yes	Family name.
tenantCode	Yes	The tenant to register in.
continueAsPatientToken	No	From a "continue as a patient" link; see business-email sign-up.

Response

On success the answer is the same as a finished sign-in:

Response field	Example	Meaning
accessToken	Token string	Bearer token for API calls.
refreshToken	Token string	Token used to renew the session.
expiresIn	3600	Access-token lifetime in seconds.
project.reference, project.display	Project/<id>, Big Health Company	Project the tokens are for.
profile.reference, profile.display	Patient/<id>, Ada Lovelace	Patient profile that was registered.

A welcome email (PATIENT_WELCOME) is sent in the background, and only if that template is mapped. The response does not wait for it.

The one other success answer is { "nextStep": "clinician-invite" }, with no tokens; see business-email sign-up.

What can go wrong

Checks run in this order, so the first one that fails is the one you see.

Order	Status	Message	Cause
1	429		More than 5 requests in a minute from the same IP address.
2	404	Tenant not found.	The tenant code is wrong.
3	403	Registration is not enabled for this project.	The project has no default patient AccessPolicy.
4	403	Registration is not enabled for this project.	PATIENT_REGISTRATION_ENABLED is false.
5	400	Registration failed.	A patient with this email already exists in this project.
6	400	The continue-as-patient link is invalid or has expired.	A continueAsPatientToken was sent and is wrong, expired, or for another email or project.

Steps 3 and 4 give the same message. If you did not turn the switch off, check the default patient AccessPolicy first. A body field that is missing or invalid answers 422 with a list of path and message.

Business-email sign-up

Some projects want colleagues from a company to become practitioners, not patients. With CLINICIAN_INVITE_ON_BUSINESS_EMAIL on, a registration with a business address creates a practitioner invitation instead of a patient. A business address is one that is neither free mail nor a throwaway domain.

The call then answers { "nextStep": "clinician-invite" } with no tokens, and Ovok emails an invitation with a link to set a password as a practitioner. The email also carries a "continue as a patient" link; send its continueAsPatientToken back in this request to register as a patient anyway. The token is valid for 7 days and only for the same email in the same project. An invalid or expired token answers 400 The continue-as-patient link is invalid or has expired.

The invitation goes out only when all of these hold:

• patient registration would otherwise succeed (the two requirements above);
• the setting is true (how to set it);
• DEFAULT_PRACTITIONER_ACCESS_POLICY resolves to a valid policy;
• a PRACTITIONER_APP_URL resolves, for the set-password link;
• a PATIENT_APP_URL resolves, for the "continue as a patient" link;
• the invitation email can be sent: CLINICIAN_SIGNUP_INVITE is mapped and its provider is ready.

If any condition fails, the person is registered as a patient and you are not told; the reason is only logged. An email that already has an account in any project answers 400 Registration failed.

Gotchas

• Registration returns tokens even when PATIENT_LOGIN_ENABLED is false. To stop patients signing up, use the registration switch.
• Turning registration off does not stop every way to create a patient. Invitations create patients too, while PATIENT_INVITATION_ENABLED is on, and first-time Google or Apple sign-in does as well. Turn the invitation switch off for an invitation-free project.
• Off and "not configured" look the same. Steps 3 and 4 return one message.
• Handle nextStep. A client that always expects accessToken breaks on clinician-invite.
• Projects created with POST /v1/slim/project/child start with registration off and no default patient AccessPolicy.
• Every error takes at least a second, so a spinner is the right UI.

Related

• Email templates, for the welcome and invitation emails
• Patient sign-in
• PATIENT_REGISTRATION_ENABLED
• Set up your project