OAuth flowsTwo distinct authorization models are supported, depending on whether access is tied to an individual patient or to a system acting on its own behalf.Patient Access API uses the authorization code flow, where the patient authenticates and consents to data access. All API requests made with the token are performed on behalf of the authenticated patient and only return data the patient is permitted to see.Provider Directory API uses the client credentials flow, and there is no login or consent step. This token grants system-level, read-only access to publicly available provider directory data and is not associated with an individual patient.Authorization code flow (Patient Access API)- Redirect the member to the authorization endpoint with
response_type=code, your client_id, and your registered redirect_uri. - Include the following SMART scopes:
openid, fhirUser, launch/patient, and patient/*.rs. No other scopes are supported for Patient Access API tokens, including specific FHIR resource or wildcard scopes. - The authorization server redirects back with an auth code.
- Exchange the auth code for tokens at the token endpoint using Basic authentication (
client_id:client_secret).
Example authorization requestGET <authorization_endpoint>?response_type=code
&client_id=<client_id>
&redirect_uri=https://client-app.com/redirect
&scope=openid fhirUser launch/patient patient/*.rs
Example redirect responsehttps://client-app.com/redirect?code=<auth_code>
Example auth code exchangePOST <token_endpoint>
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
code=<auth_code>
redirect_uri=https://client-app.com/redirect
Client credentials flow (Provider Directory API)- Call the token endpoint directly with
grant_type=client_credentials. - Request the system-level scope
system/*.rs. No other scopes are supported for Provider Directory API tokens. - Use the returned access token to call the API.
Example client credentials requestPOST <token_endpoint>
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
scope=openid fhirUser system/*.rs
Example token response{
"access_token": "<access_token>",
"scope": "openid fhirUser launch/patient patient/*.rs",
"id_token": "<id_token>",
"token_type": "Bearer",
"expires_in": 3599
}Example FHIR requestcurl --request GET --url <fhir_endpoint> --header 'Authorization: Bearer <access_token>'
Refresh token redemptionIf your authorization flow returned a refresh token, you can exchange it for a new access token by calling the token endpoint again.
Example refresh token requestPOST <token_endpoint>
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
refresh_token=<refresh_token>