# Patient sign-in

Canonical page: https://docs.ovok.com/authentication/patient-login

A patient signs in to the tenant they belong to. The flow has up to three steps: start, an optional multi-factor step, and a token exchange.

| Step | Method | Path |
| --- | --- | --- |
| 1 | `POST` | `/v1/auth/tenant/Patient/login/start` |
| 2, only with MFA | `POST` | `/v1/auth/tenant/Patient/login/mfa` |
| 3 | `POST` | `/v1/auth/tenant/Patient/login/token` |

None of the three needs a bearer token.

## Before you start [#before-you-start]

| You need | Where it comes from |
| --- | --- |
| The tenant code | [Find your tenant code](/authentication/project-setup#1-find-your-tenant-code). |
| A patient account in that project | [Patient registration](/authentication/patient-registration) or a [patient invitation](/settings-and-features/settings/patient-invitation-enabled). |
| Patient sign-in switched on | [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/patient-login-enabled) must not be `false`. It is on when unset. |

The account must be a **Patient of that tenant's project**. A practitioner with the same email cannot sign in here; use [practitioner sign-in](/authentication/practitioner-login).

## Step 0: Create a code verifier and challenge [#step-0-create-a-code-verifier-and-challenge]

Create these in your app for every sign-in attempt, and keep the verifier until step 3. The verifier is a random string of 43 to 128 URL-safe characters; the challenge is its SHA-256 hash, base64url-encoded without padding.

```js
const base64url = (bytes) =>
  btoa(String.fromCharCode(...new Uint8Array(bytes)))
    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

const codeVerifier = base64url(crypto.getRandomValues(new Uint8Array(48)));
const codeChallenge = base64url(
  await crypto.subtle.digest('SHA-256', new TextEncoder().encode(codeVerifier)),
);
```

The same in a shell:

```bash
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
```

## Step 1: Start sign-in [#step-1-start-sign-in]

Checks the email and password for one tenant.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/login/start' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "patient@example.com",
    "password": "your-password",
    "tenantCode": "big-health-company",
    "codeChallenge": "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"
  }'
```

| Body field | Description |
| --- | --- |
| `email` | The patient's email. Ovok lowercases it. |
| `password` | The patient's password. |
| `tenantCode` | The tenant to sign in to. |
| `codeChallenge` | The hash from step 0. |

The answer tells you what to do next:

| Response field | Example | Meaning |
| --- | --- | --- |
| `nextStep` | `token` or `mfa` | Tells the app which sign-in step to show next. |
| `sessionCode` | Temporary code | Present when `nextStep` is `token`; send it with the verifier in step 3. |
| `loginId` | UUID | Present when `nextStep` is `mfa`; send it with the one-time code in step 2. |

| Status | Message | Cause |
| --- | --- | --- |
| `404` | `Tenant not found.` | The tenant code is wrong. Checked first. |
| `403` | `Login is not enabled.` | [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/patient-login-enabled) is `false`. |
| `401` | `Invalid email or password.` | A wrong email, an unknown account, an account without a password, a wrong password, or an account that is not a patient of this tenant. All give the same answer on purpose. |
| `400` | `Username or password is incorrect.` | The sign-in could not be started after the password was accepted. Retry. |
| `422` | A list of `path` and `message` | A body field is missing or invalid. |
| `429` | | More than 10 requests in a minute, or 5 failed sign-ins for this email within 15 minutes. The account then stays locked for 15 minutes; the body's `retryAfterSec` says how many seconds are left. |

## Step 2: Verify the one-time code (only with MFA) [#step-2-verify-the-one-time-code-only-with-mfa]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/login/mfa' \
  --header 'Content-Type: application/json' \
  --data '{"loginId":"8c1e5a52-6f0b-4d9e-9a41-0b2f7c3d9e10","mfaToken":"123456"}'
```

| Body field | Description |
| --- | --- |
| `loginId` | The `loginId` from step 1. A UUID. |
| `mfaToken` | The current one-time code from the patient's authenticator app, at least 6 characters. |

On success the answer is `{ "nextStep": "token", "sessionCode": "…" }`. Use the `sessionCode` in step 3.

| Status | Message | Cause |
| --- | --- | --- |
| `400` | `Invalid MFA token.` | The code is wrong or expired, or the `loginId` is unknown. |
| `422` | A list of `path` and `message` | `loginId` is not a UUID, or `mfaToken` is shorter than 6 characters. |
| `429` | | More than 5 requests in a minute. Few guesses are allowed on purpose. |

## Step 3: Exchange the session code for tokens [#step-3-exchange-the-session-code-for-tokens]

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/login/token' \
  --header 'Content-Type: application/json' \
  --data '{"sessionCode":"<sessionCode from step 1 or 2>","codeVerifier":"<your code verifier>"}'
```

This step takes no tenant code: the session code already belongs to the tenant you started 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>`, `Example Patient` | Patient profile that signed in. |

| Status | Message | Cause |
| --- | --- | --- |
| `400` | `Code verification failed.` | The `sessionCode` or the `codeVerifier` is wrong. |
| `400` | `Invalid user profile.` | The session belongs to something other than a patient. |
| `400` | `Account not found.` | The patient account could not be found. |
| `429` | | More than 30 requests in a minute. |

If the patient had scheduled their account for deletion, signing in cancels the deletion.

## End to end in a shell [#end-to-end-in-a-shell]

This signs in a patient who has no multi-factor step. It needs `jq`.

```bash
VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
CHALLENGE=$(printf %s "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

SESSION=$(curl --silent --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/login/start' \
  --header 'Content-Type: application/json' \
  --data "{\"email\":\"patient@example.com\",\"password\":\"${PASSWORD}\",\"tenantCode\":\"big-health-company\",\"codeChallenge\":\"${CHALLENGE}\"}" \
  | jq -r '.sessionCode')

curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/auth/tenant/Patient/login/token' \
  --header 'Content-Type: application/json' \
  --data "{\"sessionCode\":\"${SESSION}\",\"codeVerifier\":\"${VERIFIER}\"}"
```

## Gotchas [#gotchas]

- **The setting is checked at step 1 only.** A session code issued before you turned [`PATIENT_LOGIN_ENABLED`](/settings-and-features/settings/patient-login-enabled) off can still be exchanged at step 3.
- **Turning the switch off does not end sessions.** A patient who is already signed in keeps working until their token expires, up to an hour.
- **Registration returns tokens too.** A patient who registers is signed in even if sign-in is off. Use [`PATIENT_REGISTRATION_ENABLED`](/settings-and-features/settings/patient-registration-enabled) to stop registration.
- **Projects created with `POST /v1/slim/project/child` start with patient sign-in off.** Turn it on before you launch.
- **A failed read of the project looks like "off".** If the project cannot be read for a moment, callers see the `403`.
- **Keep the verifier private.** Do not send it anywhere before step 3, and do not reuse it across sign-in attempts.
- **Every error takes at least a second.** Show a spinner, not an outage message.

## Related [#related]

- [Practitioner sign-in](/authentication/practitioner-login)
- [Patient registration](/authentication/patient-registration)
- [Errors and troubleshooting](/authentication/troubleshooting)
