OAuth flows
Two 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 request
GET <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 response
https://client-app.com/redirect?code=<auth_code>
Example auth code exchange
POST <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 request
POST <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 request
curl --request GET --url <fhir_endpoint> --header 'Authorization: Bearer <access_token>'
Refresh token redemption
If 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 request
POST <token_endpoint>
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
refresh_token=<refresh_token>