Quickstart

Go from nothing to a working SMART on FHIR app against your synthetic Ava sandbox: register a public client, complete an EHR launch with authorization code + PKCE S256, and read your first Patient resource. No client secret is involved anywhere in this flow.

Before you start

• An Ava Ecosystem account and an organization (sign up takes a minute).
• Ruby 3.x locally if you want to run the sample app (ruby -v).

1. Activate your sandbox

From your organization dashboard, press Activate sandbox. Ava provisions a synthetic clinic (dataset ontario_primary_care_v1) and a sandbox EMR login for you. Wait for the sandbox card to show Active — it also gives you the EMR login email and sign-in link you'll use in step 5.

2. Register your app

Create a developer app, then open its sandbox configuration and set exactly:

Sandbox HTTP URIs must use a loopback IP literal — localhost is rejected, 127.0.0.1 is accepted. (Deployed apps use HTTPS URIs.)

3. Choose scopes

In your app's permission schema, select openid, fhirUser, and patient/Patient.r, with a short rationale for each. The core launch scope is always included automatically. You can expand scopes later — users are asked to re-consent when you add access.

4. Deploy to your sandbox

Press Deploy to my sandbox on the app page. When the sandbox registration card shows your public client ID, the registration is live: sign in to see yours.

5. Run the sample app and launch from the EMR

The repository ships a single-file SMART client that proves the whole flow — EHR launch → authorization code + PKCE S256 → token exchange → Patient read:

CLIENT_ID=<your public client id> ruby app.rb

Then sign in to the sandbox EMR with the login from step 1, open any synthetic patient, and press your app's launch button. Approve the SMART authorization screen and the test app shows each completed step: token exchange, OpenID identity, and the launched patient fetched over FHIR.

The sandbox supports the EHR launch only — browsing to the app directly shows a waiting page until a launch arrives.

6. Call the API directly

Every FHIR request is a plain HTTPS call with the access token from the launch:

curl "https://sandbox.avaemr.ca/fhir/r4/{partition_id}/Patient/{id}" \
  -H "Authorization: Bearer $SMART_ACCESS_TOKEN" \
  -H "Accept: application/fhir+json"

Responses are FHIR R4 JSON (application/fhir+json); errors are FHIR OperationOutcome resources. The discovery documents at https://sandbox.avaemr.ca/fhir/r4/{partition_id}/metadata and https://sandbox.avaemr.ca/.well-known/smart-configuration are the authoritative, machine-readable description of the API surface.

Next steps

• App launch & PKCE in depth — every request in the flow.
• Integration brief — the condensed one-page contract, ideal context for coding agents.