Practitioner registration

Creates a practitioner account in a tenant and signs the practitioner in straight away. It is off by default: turn it on only if you want anyone who can reach the route to become a practitioner of your project.

Method	Path
POST	/auth/tenant/Practitioner/register

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

What the project needs

Requirement	Detail
Registration switched on	PRACTITIONER_REGISTRATION_ENABLED must be true. It is off when unset.
A default practitioner AccessPolicy	DEFAULT_PRACTITIONER_ACCESS_POLICY must be AccessPolicy/<id> of a policy in this project. Every registered practitioner receives it.

Set the policy first, then switch registration on. The commands are in set up your project. With the switch on and no valid policy, the route answers 409 rather than creating a practitioner without limits.

Request

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

Body field	Required	Description
email	Yes	The practitioner's email. Ovok lowercases it.
password	Yes	1 to 128 characters. Enforce your own password rules in your app.
name	Yes	Given name.
surname	Yes	Family name.
tenantCode	Yes	The tenant to register in.

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	Practitioner/<id>, Grace Hopper	Practitioner profile that was registered.

The account, the practitioner profile and the membership are created together or not at all. No email is sent.

What can go wrong

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

Order	Status	Response	Cause
1	429		More than 5 requests in a minute from the same IP address.
2	422	A list of path and message	A body field is missing or invalid, for example an empty password.
3	404	Tenant not found.	The tenant code is wrong.
4	403	Registration is not enabled for this project.	PRACTITIONER_REGISTRATION_ENABLED is not true.
5	409	error practitioner_registration_not_configured	Registration is on, but there is no valid default practitioner AccessPolicy.
6	409		Another registration for the same email is in progress. Retry.
7	400	Registration failed.	The email already has an account.

Gotchas

• The email check spans Ovok. A practitioner whose email already has an account in any project gets 400 Registration failed. The message is generic and does not say why. Add that person to your project with a practitioner invitation instead.
• A policy that stops being valid breaks registration. If the AccessPolicy is deleted, cannot be read, or belongs to another project, step 5 returns 409 until you set a valid one. Changing the policy does not touch practitioners who already registered.
• Registration returns tokens even when PRACTITIONER_LOGIN_ENABLED is false.
• The new account is signed in immediately and nothing confirms the email address. Do not treat a registration as proof that the person owns the address.
• Choose the policy with care. With the switch on, the default policy is what a stranger gets.
• Every error takes at least a second, so a spinner is the right UI.

Related

• Practitioner sign-in
• PRACTITIONER_REGISTRATION_ENABLED
• DEFAULT_PRACTITIONER_ACCESS_POLICY
• Set up your project