Skip to main content

Authorization Review

Description
  • Our APIs are protected by an OAuth 2.0 authorization server powered by Okta.
  • App developers who register with athenahealth receive OAuth client credentials.
  • The OAuth client credentials are used to request access tokens from our authorization server.
  • Access tokens are JSON web tokens (JWTs) and represent authorized access for an app to API endpoints.
  • Access tokens are required for successful requests to read, write, or update data in athenaOne.
  • Our platform offers various methods for app authorization to obtain an access token for accessing API endpoints in athenaOne.

Authorization Methods​

2-legged OAuth
  • 2-legged OAuth allows apps to use their OAuth client credentials to obtain an access token.
  • This method is used for service-to-service access to data in athenaOne
  • Customers of athenahealth authorize an app to access specific endpoints for their organization.
  • Our implementation of 2-legged OAuth follows the client credentials grant type defined by OAuth 2.0.
3-legged OAuth
  • 3-legged OAuth requires apps to obtain end user authorization in addition to providing client credentials to obtain an access token.
  • This method is used for patient-facing and provider-facing apps accessing data in athenaOne on behalf of an end user.
  • Our implementation of 3-legged OAuth follows the authorization code grant type defined by OAuth 2.0.
  • You must select either 2-legged OAuth or 3-legged OAuth as your authorization method when registering your app.
  • You cannot use a single set of OAuth credentials for both.
  • You can use your app’s provisioned OAuth credentials to authenticate and retrieve an access token from the environment-specific OAuth token endpoint by two methods:

1. Calling the token endpoint directly (2-legged OAuth)​

2 . Requesting and obtaining end user authorization.​

If necessary, from the OAuth authorize endpoint (3-legged OAuth). Additional OAuth endpoints we support can be found here.

OAuth Scopes​

info
  • The level of API access afforded to an access token is determined by the OAuth scopes granted from the token request.
  • An OAuth scope represents a permission – i.e., the “scope” of an app’s access request – where that request, and in turn that permission, may be granted or denied by the authorization server.
  • Each of athenahealth’s API endpoints corresponds to one or more scopes, where an app must request and be granted an access token with that endpoint’s required scope(s) to call the endpoint successfully.
  • Additional scopes may determine the types of calls you can make to a given endpoint, for example to perform a specific app launch or to vary the format of the API response.
  • Apps can request scopes either by calling the token endpoint or authorize endpoint.

OAuth Scopes Request Checks​

info

Your app’s scope request must pass the following checks to determine whether each scope within the request is granted:

  • Is the scope included in the scope parameter of the request?
  • Is the scope approved for your app’s OAuth client credentials?
  • If the scope requires end user consent (3-legged OAuth only), did the user grant that consent when prompted?
  • All scopes included in the request must pass the first two checks or the request will fail.
  • If all requested scopes pass the first two checks and end user consent is required for one or more of those scopes, then the user’s consent decision will determine the outcome of the request:
  • If the user denies all requested scopes when prompted, then the request will fail.
  • If the user grants one or more requested scopes, then the request will succeed.
  • However, any scope the user denies will be omitted from the access token obtained through that request, preventing the app from accessing API endpoints requiring that scope.
  • You can check which scopes were granted from your app’s request using token introspection.
Available Scopes for 2-Legged OAuth Apps

athenahealth automatically approves all 2-legged OAuth Preview apps for the following scopes upon request through the Developer Portal console:

athena/service/MDP.*

Automatic approval of scopes for 2-legged OAuth apps also extends to those FHIR scopes corresponding to US Core resources and athenahealth’s certified APIs. All FHIR APIs require the use of OAuth scopes using the SMART App Launch Framework v1.0.0 clinical scope syntax.

The syntax for these scopes is:

clinical-scope = ('patient' | 'user' | 'system') '/' ([fhir-resource] | '*') '.' ('read' | 'write' | '*')

For example, “system/AllergyIntolerance.read” would allow an application to read a patient’s AllergyIntolerance information.

By default, athenahealth does not permit apps to request wildcard scopes (those containing “”, such as “system/.read”, “system.AllergyIntolerance.”, or “system/.*”), which provide access to all FHIR resources or permissions, nor does athenahealth permit write scopes (e.g., system/AllergyIntolerance.write).

List of FHIR resource scopes automatically approved for 2-legged OAuth apps upon request through the Developer Portal console

  • system/AllergyIntolerance.read
  • system/Binary.read
  • system/CarePlan.read
  • system/CareTeam.read
  • system/Condition.read
  • system/Device.read
  • system/DiagnosticReport.read
  • system/DocumentReference.read
  • system/Encounter.read
  • system/Goal.read
  • system/Immunization.read
  • system/Location.read
  • system/Medication.read
  • system/MedicationRequest.read
  • system/Observation.read
  • system/Organization.read
  • system/Patient.read
  • system/Practitioner.read
  • system/Procedure.read
  • system/Provenance.read

Note:​

The scopes listed above are for 2-legged access using scopes of type “system”, whereas scopes of type “user” and “patient” are exclusive to 3-legged access.

Available Scopes for 3-Legged OAuth Apps

athenahealth automatically approves all 3-legged OAuth apps for the following scopes upon request through the Developer Portal console:

  • openid
  • fhirUser
  • offline_access

Automatic approval of scopes for 3-legged OAuth apps also extends to the necessary scopes for each app’s intended SMART App Launch sequence, as well as those FHIR scopes corresponding to US Core resources and athenahealth’s certified APIs. All FHIR APIs require the use of OAuth scopes using the SMART App Launch Framework v1.0.0 clinical scope syntax. The syntax for these scopes is:

clinical-scope = ('patient' | 'user' | 'system') '/' ([fhir-resource] | '*') '.' ('read' | 'write' | '*')

For example, “patient/AllergyIntolerance.read” would allow an application to read a patient’s AllergyIntolerance information on that patient’s behalf.

By default, athenahealth does not permit apps to request wildcard scopes (those containing “”, such as “patient/.read”, “patient.AllergyIntolerance.”, or “patient/.*”), which provide access to all FHIR resources or permissions, nor does athenahealth permit write scopes (e.g., patient/AllergyIntolerance.write).

For patient-facing apps using 3-legged OAuth, the following scopes are automatically approved upon request through the Developer Portal console for use with the standalone SMART App Launch sequence:

  • launch/patient
  • patient/Appointment.read
  • patient/Assessment.read
  • patient/Binary.read
  • patient/AllergyIntolerance.read
  • patient/CarePlan.read
  • patient/CareTeam.read
  • patient/ClinicalImpression.read
  • patient/Condition.read
  • patient/Device.read
  • patient/DiagnosticReport.read
  • patient/DocumentReference.read
  • patient/Encounter.read
  • patient/Goal.read
  • patient/Immunization.read
  • patient/Location.read
  • patient/MedicalAdministration.read
  • patient/Medication.read
  • patient/MedicationDispense.read
  • patient/MedicationOrder.read
  • patient/MedicationRequest.read
  • patient/MedicationStatement.read
  • patient/Observation.read
  • patient/Organization.read
  • patient/Patient.read
  • patient/PracticeConfiguration.read
  • patient/Practitioner.read
  • patient/Procedure.read
  • patient/Provenance.read
  • patient/Provider.read

For provider-facing apps using 3-legged OAuth, the following scopes are automatically approved upon request through the Developer Portal console for use with the Provider EHR SMART App Launch sequence:

  • launch
  • user/AllergyIntolerance.read
  • user/Appointment.read
  • user/Assessment.read
  • user/Binary.read
  • user/CarePlan.read
  • user/CareTeam.read
  • user/ClinicalImpression.read
  • user/Condition.read
  • user/Device.read
  • user/DiagnosticReport.read
  • user/DocumentReference.read
  • user/Encounter.read
  • user/Goal.read
  • user/Immunization.read
  • user/Location.read
  • user/MedicalAdministration.read
  • user/Medication.read
  • user/MedicationDispense.read
  • user/MedicationOrder.read
  • user/MedicationRequest.read
  • user/MedicationStatement.read
  • user/Observation.read
  • user/Organization.read
  • user/Patient.read
  • user/PracticeConfiguration.read
  • user/Practitioner.read
  • user/Procedure.read
  • user/Provenance.read
  • user/Provider.read

Note: The scopes listed above are for 3-legged access using scopes of type “patient” and “user”. Scopes of type “system” are exclusive to 2-legged access, such as system-to-system calls that do not include a user.

Reference​

https://docs.athenahealth.com/api/guides/authorization-overview