> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User Registration

> The order of calls that takes a patient from no identity to holding their own access and refresh tokens.

## 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.

> [!NOTE]
>
> 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](https://openloop.mintlify.site/auth/obtain-token.md) for more details.

```bash theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>",
    "audience": "https://api.openloophealth.com"
  }'
```

See [Obtain a service token](https://openloop.mintlify.site/auth/obtain-token.md) 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.

```bash theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/register \
  -H "Authorization: Bearer <service_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "phone_number": "+15550123456",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
```

```json 201 theme={null}
{
  "data": {
    "id": "7g4k9p2m1x8q",
    "status": "pending_verification"
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

See [Register a user](https://openloop.mintlify.site/auth/register.md) 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.

```bash theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/send-otp \
  -H "Authorization: Bearer <service_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "channel": "email"
  }'
```

See [Send a one-time login/verification code](https://openloop.mintlify.site/auth/send-otp.md) 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.

```bash theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/verify-otp \
  -H "Authorization: Bearer <service_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@example.com",
    "code": "482913"
  }'
```

See [Verify a one-time code](https://openloop.mintlify.site/auth/verify-otp.md) for the full reference.

> [!NOTE]
>
> **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`.

```bash theme={null}
curl -X POST https://api.openloophealth.com/v0.1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "urn:openloophealth:oauth:grant-type:verification-code",
    "code": "<verification_code>",
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
  }'
```

See [Exchange a verification code](https://openloop.mintlify.site/auth/exchange-verification-code.md) for the full reference.

> [!TIP]
>
> 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](https://openloop.mintlify.site/auth/refresh-token.md).
* **Revoke** with `POST /auth/revoke` to end a session on logout. See [Revoke a token](https://openloop.mintlify.site/auth/revoke.md).
* **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](https://openloop.mintlify.site/users/delete-user.md).

## Related

> [card] [Obtain a service token](https://openloop.mintlify.site/auth/obtain-token.md)
>
> The client\_credentials grant used in steps 2-4

> [card] [API Reference](https://openloop.mintlify.site/api-reference/introduction.md)
>
> Endpoint details and schemas


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.