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

# Getting started

> Get a bearer token from POST /v0.1/auth/token on staging, use the fixed audience, and reach your first resource endpoint.

Start here. Every other page assumes you have a working token and know which host to call.

## What you'll do

**1. Point at the right host**

Build against staging, with the credentials issued for it.

**2. Exchange your credentials for a token**

`POST /v0.1/auth/token` with a JSON body, then read `data.access_token`.

**3. Call a resource endpoint**

Send the token as a bearer header and read the `items` / `data` envelope back.

**4. Run your first five calls**

Confirm your tenant is provisioned before you write any integration code.

## Hosts

| Environment | Host |
| - | - |
| Staging — build and test here | `https://api-staging.openloophealth.com` |
| Production | Confirm with your OLH implementation contact before your first production call |
| `audience` (all environments) — a token-request value, not a host you call | `https://api.openloophealth.com` |

## The partner surface is `/v0.1`

Every resource you need is under `/v0.1` — patients, questionnaires, questionnaire-responses,
encounters, products, prices, checkouts, orders, subscriptions.

That includes authentication: the token endpoint is **`/v0.1/auth/token`**. `/v1` paths are not
part of the partner surface — do not call them.

## Recipe 1.2 · Your first five calls

Run these in order before writing any integration code. If any fails, stop and report it — the
rest of the cookbook assumes they pass.

1. `POST /v0.1/auth/token` → `200`, and `data.access_token` is present
2. `GET /v0.1/patients` → `200` with an `items` array
3. `GET /v0.1/questionnaires?status=active` → `200`, and at least one form
4. `GET /v0.1/products?active=true` → `200`, and at least one product
5. `GET /v0.1/configs` → `200`, with a payment provider and an active status

Steps 3 and 4 depend on your tenant being seeded. An empty result is not a bug in your code — see
*Known gaps and staging*.

> [!TIP]
>
> Locked by check `first-five-calls`.

### Call 1 — the token exchange

Client-credentials, JSON body — not form-encoded.

```bash curl theme={null}
curl -X POST https://api-staging.openloophealth.com/v0.1/auth/token \
  -H 'content-type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<your client id>",
    "client_secret": "<your client secret>",
    "audience": "<the fixed audience from the Hosts table>"
  }'
```

```json Response theme={null}
{
  "data": {
    "access_token": "eyJ...",
    "token_type": "Bearer",
    "expires_in": 3600
  },
  "request_id": "..."
}
```

> [!WARNING]
>
> **`audience` is a fixed string, not the host you are calling.** Use the `audience` value from the
> Hosts table above even when you are calling `api-staging`. Setting it to the staging host will
> fail.

The token is nested under `data`, matching the published `AuthTokenResponse` schema.

Read `expires_in` rather than hard-coding a lifetime — it differs between environments, and
production tokens are short-lived. Refresh before expiry; do not retry on `401` without
re-exchanging.

### Calls 2 to 5 — send the token

Send it as a bearer token on every call:

```bash theme={null}
curl https://api-staging.openloophealth.com/v0.1/patients \
  -H "authorization: Bearer $TOKEN"
```

## What comes back

| Field | Meaning | You key on it for |
| - | - | - |
| `data.access_token` | The bearer token, nested under `data` | The `authorization: Bearer …` header on every other call |
| `expires_in` | Token lifetime in seconds; it differs between environments | Refreshing before expiry rather than retrying on `401` |
| `items[]` | A collection read | Listing, and telling "none yet" from "not seeded" |
| `after` | The clinical cursor, when there is a next page | Paging clinical resources |
| `pagination` | An object on `products` only; catalogue paging is not implemented yet | Nothing yet — do not build a cursor loop on it (see *API status*, "Response envelopes differ by endpoint") |
| `data` | A single read or a write: the resource itself, wrapped | Reading back what you created |
| `request_id` | Present on every response, success or failure | Support, on every call — including the ones that worked |
| `error.error_code` | The machine-readable failure cause — `VALIDATION_ERROR`, `NOT_FOUND` | Branching on a failure without matching message text |

**Collections** return an `items` array. Clinical resources page with an `after` cursor (present
only when there is a next page). The product catalogue carries a `pagination` object, but
catalogue paging is not implemented yet, so do not build a cursor loop on it. Do not write one shared pagination helper — see
*API status*, "Response envelopes differ by endpoint", for the full picture.

```json theme={null}
{ "items": [ ... ], "request_id": "...", "after": "..." }
```

**Writes** return the created resource under `data`, not `items`:

```json theme={null}
{ "data": { "id": "...", ... }, "request_id": "..." }
```

> [!TIP]
>
> Locked by check `writes-return-data-reads-return-items`.

**Errors** carry a message and a code:

```json theme={null}
{ "error": { "message": "phone: phone must be E.164 format", "error_code": "VALIDATION_ERROR" },
  "request_id": "..." }
```

> [!NOTE]
>
> **Always log `request_id`.** It is on every response, success or failure, and it is the fastest way
> for support to find your exact call. A problem report without one usually costs a round trip.

> [!TIP]
>
> Locked by check `request-id-on-success-and-failure`.

## Gotchas

> [!WARNING]
>
> **Staging and production use different credentials.** A client id/secret pair issued for one
> environment will not authenticate against the other. A staging credential presented to the
> production host is also rejected at the gateway with a misleading error — keep the two
> configurations separate from the start.

> [!NOTE]
>
> `audience` is not the host — see *FAQ and troubleshooting* if that distinction is unclear.

**Reading an error correctly.** Three different failures all arrive as `403`, and they need
different responses from you:

| Error mentions | Meaning | What to do |
| - | - | - |
| `insufficient_permissions` | Your credential lacks a scope | Report it with the `request_id` |
| The `Authorization` header, a missing `Credential` parameter, or an invalid `key=value` pair | **Usually the wrong HTTP method for that path**, not a permission problem | Check the reference for the method that path accepts. `/checkouts/sessions` is `POST`-only. Only conclude an endpoint is unavailable after trying the documented verb |
| A payment-provider permission, e.g. `payment_method_configurations_read` | A configuration gap on the OpenLoop side | Report it with the `request_id`. It does not block checkout |

## Related

> [card] [Start here](https://openloop.mintlify.site/cookbook/index.md)
>
> The seven stages in build order, what to read first, and the reference pages

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> The whole journey — patient, intake, encounter, payment — as a sequence

> [card] [Errors](https://openloop.mintlify.site/cookbook/errors.md)
>
> When a call here fails: the error envelope, and what each status means by endpoint family


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