Authorization Overview

Our APIs are secured by an OAuth 2.0 authorization server powered by Okta. App developers that register with athenahealth are therefore issued OAuth client credentials used to request access tokens (a type of JSON web token, or “JWT” – pronounced “jot”) from our authorization server. An access token represents an app’s authorized access to one or more API endpoints used to read, write, or update data in athenaOne, where an app is required to provide an access token to make a successful request to those endpoints.

Our platform supports the following methods for your app to obtain authorization (i.e., an access token) for accessing API endpoints used to read, write, or update data in athenaOne:

  • 2-legged OAuth, in which apps use their OAuth client credentials to obtain an access token. This method is used for service-to-service access to data in athenaOne, where athenahealth customers have authorized an app to access a specific set of endpoints for their organization. Our implementation of 2-legged OAuth uses the client credentials grant type as defined by OAuth 2.0.
  • 3-legged OAuth, in which apps must get end user authorization to obtain an access token, in addition to providing their client credentials. This method is used for patient- and provider-facing apps accessing data in athenaOne on behalf of an end user. Our implementation of 3-legged OAuth uses the authorization code grant type as 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, either by calling the token endpoint directly (2-legged OAuth) or by 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

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. Your app’s scope request must pass the following checks to determine whether each scope within the request is granted:

  1. Is the scope included in the scope parameter of the request?
  2. Is the scope approved for your app’s OAuth client credentials?
  3. 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).

Below is the 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.

Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others
Submit

On this Page