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

# Quickstart

> Get a token, enroll a patient and call the API as a brand server, a patient and a prescriber system.

Everything here runs against the [sandbox](https://docs.tera.health/sandbox.md), a mock built from the contract that answers every operation with the examples on these pages. Use synthetic data only. To work offline, [run the mock yourself](#run-the-mock-yourself) and set `BASE=http://localhost:4010`.

```bash theme={null}
BASE=https://sandbox.rx.tera.health
```

**1. Get a brand server token**

Brand servers use OAuth client credentials. Keep the secret in your server's environment, never in code. In the sandbox any client id and secret work.

```bash theme={null}
curl -s $BASE/v1/oauth/token \
  -u "$TERARX_CLIENT_ID:$TERARX_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=enrollments:read enrollments:write"
```

> [!NOTE]
>
> **Platform partners** (one client for several brands): add the brand with `-d tenant_id=<the brand's id>`. Every token is for one brand, so keep one token per brand. `GET /v1/tenants` lists your brands. See [Platform partners](https://docs.tera.health/guides/partners.md).

Copy `access_token` from the response into `TOKEN`. It lasts 1 hour; cache it rather than fetching one per call.

```bash theme={null}
TOKEN=trx_at_example_not_a_real_token
```

**2. Enroll a patient**

Call this at checkout. Use one `Idempotency-Key` per checkout and send the same key on every retry, so a retried checkout can't enroll twice.

```bash theme={null}
curl -s $BASE/v1/enrollments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-ord-2026-10-000123" \
  -d '{
    "external_patient_id": "brand-pt-48213",
    "patient": { "first_name": "Jordan", "last_name": "Rivera", "email": "jordan.rivera@example.com",
      "date_of_birth": "1986-04-12", "sex": "female", "state_code": "NY", "timezone": "America/New_York" }
  }'
```

The response is the enrollment, with its `id` and `stage`.

**3. Get a patient token**

Your server signs a short-lived assertion for the patient with your own key, and your app exchanges it for a 15-minute patient token. Platform partners add a `tenant_id` claim naming the patient's brand. The [patient token sample](https://docs.tera.health/samples.md#patient-token) does both; put its assertion in `ASSERTION`.

```bash theme={null}
curl -s $BASE/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d subject_token=$ASSERTION \
  -d subject_token_type=urn:ietf:params:oauth:token-type:jwt
```

Then call patient endpoints with that token, starting with `GET /v1/patient`.

**4. Read clinical flags as the prescriber system**

Your prescriber system has its own client with `clinical:read` and `clinical:write`. Get its token the same way as in step 1, then list open flags.

```bash theme={null}
curl -s "$BASE/v1/clinical-flags?status=open" -H "Authorization: Bearer $CLINICAL_TOKEN"
```

**5. Receive webhooks**

Verify `TeraRx-Signature` on the raw body before you trust a delivery. The [webhook sample](https://docs.tera.health/samples.md#webhook-verification) checks the worked example from the [Webhooks](https://docs.tera.health/guides/webhooks.md) guide.

## Postman

Import the [collection](https://sandbox.rx.tera.health/docs/postman/terarx-v1.postman_collection.json) and the [sandbox environment](https://sandbox.rx.tera.health/docs/postman/terarx-sandbox.postman_environment.json). Every operation is there with its example, and a pre-request script gets each caller its token: the brand server and the prescriber system with client credentials, the patient by exchanging `patient_assertion`. For the local mock, set `base_url` to `http://localhost:4010`.

## Run the mock yourself

Download the [bundled spec](https://sandbox.rx.tera.health/docs/openapi.json) and start [Prism](https://github.com/stoplightio/prism) on it:

```bash theme={null}
npx @stoplight/prism-cli@5.16.0 mock openapi.json --port 4010
```

Then use `http://localhost:4010` as the base URL. The samples and the API reference's playground use it too: pick it in the playground's server list.


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