Patient Access API · CMS-0057F · 42 CFR 422.119(a) · USCDI v3

For 3rd-party app developers building member-facing apps. Members sign in with their payer account; your app reads their claims, clinical data, and coverage through standards-based FHIR. Auth, consent, and metering are handled for you.

1. 1

   Register your app

   Create an application to receive a client ID and set your redirect URI.

2. 2

   Initiate PKCE authorization

   Generate a code_verifier + code_challenge pair. Redirect the member to the authorization endpoint with SMART scopes.

3. 3

   Exchange the code for tokens

   POST to /oauth2/token with the authorization code and code_verifier. Receive access_token and refresh_token.

4. 4

   Call the FHIR API

   Include the access_token as Authorization: Bearer <token>. Use the patient ID from the id_token sub claim.

5. 5

   Refresh when needed

   Access tokens expire in 1 hour. Use the refresh_token to get a new access_token without re-auth.

curl -X POST https://auth.healthchain.dev/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_CALLBACK" \
  -d "redirect_uri=https://yourapp.example/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_PKCE_VERIFIER"