Onboarding Overview

Application developers must register with athenahealth to obtain OAuth 2.0 client credentials used to access our API endpoints (refer to our authorization documentation for details). This section outlines the steps necessary to register an app with athenahealth’s platform.

Register a Developer Portal Account

If you have not done so already, you will need to register for a new athenahealth Developer Portal account. You will use these login credentials to access the Developer Portal console, where you can create and manage OAuth client credentials for your solution.

Select an App Category

When you create an app through the Developer Portal console, you will be asked to choose from an app category based on:

  • How your app will obtain access – i.e., your app’s preferred authorization method (note this is dependent on who will be authorizing access)
  • Who will be authorizing access – i.e., the app’s end users (if any) that must login and/or consent to your app reading, writing, or updating data in athenaOne
  • What your app will access – i.e., the API frameworks required to build your intended solution (certified only APIs, etc.)

If you are new to building with athenahealth, we recommend reviewing our contracting requirements and authorization documentation for further business and technical considerations when choosing between our 3 supported app categories below:

2-legged OAuth apps

  • Service-to-service apps (backend app with no end users)
  • Consent to API access is granted implicitly: Data is passed between two systems without requiring patient or provider consent
  • Access to all athenahealth APIs (athenaOne APIs, FHIR APIs, and Certified APIs)
  • Self-service access to athenaOne’s Preview environment for OAuth credentials registered via the Developer Portal console
  • Apps only using Certified APIs may request Production OAuth credentials by request to PlatformServicesSupport@athenahealth.com. All others require an athenahealth Platform Services contract to be issued Production OAuth credentials.
  • Access to an athenaOne customer's Preview or Production environment requires the signed authorization and consent of the healthcare organization.

3-legged OAuth for personal health record (PHR) apps

  • Service-to-patient-to-service apps exclusively using Certified APIs
  • Consent to API access must be granted by the end user (patient): Data is passed between two systems only if the app requests and obtains patient authorization
  • Access to Certified APIs only
  • Self-service access to both athenaOne’s Preview and Production environments for OAuth credentials registered via the Developer Portal console
  • Production OAuth credentials are automatically granted access to athenaOne customer's Preview and Production environments with no approval required.

3-legged OAuth for all other apps

  • Service-to-patient-to-service apps using 1 or more non-Certified APIs, or system-to-provider-to-system apps
  • Consent to API access must be granted by the end user (patient or provider): Data is passed between two systems only if the app requests and obtains patient or provider authorization
  • Access to Certified APIs and select other athenaOne and FHIR APIs
  • Self-service access to athenaOne’s Preview environment for OAuth credentials registered via the Developer Portal console
  • Apps only using Certified APIs may request Production OAuth credentials by request to PlatformServicesSupport@athenahealth.com. All others require an athenahealth Platform Services contract to be issued Production OAuth credentials.
  • Access to an athenaOne customer's Preview or Production environment requires the signed authorization and consent of the healthcare organization.

Once you have selected the app type most applicable to your solution, refer to the corresponding sections below for how to create OAuth credentials for your app.

Create a 2-Legged OAuth App

Follow the steps below to create a new 2-legged OAuth app.

  1. Log in to the Developer Portal console. The Applications screen will display any apps already registered to your account. Click (+) Create a New App.
  2. When prompted to choose your app category, select 2-Legged OAuth and click Continue to App Details.
  3. Complete the required fields, including details on your token authentication method. Review the required terms linked at the bottom of the page and click the checkbox to agree.
  4. Click Create Application to generate Preview OAuth credentials for your app.
  5. Copy your app credentials and store them in a secure place. If your app has been provisioned a client secret, you will not be able to view the client secret again without rotating to a new one. Please note that rotating your client secret will invalidate the previous one and may result in breaking changes in your app until references to that client secret are updated.
  6. In your app’s dashboard, click on the Scopes tab and select the OAuth scopes to which you require access. Please note that 2-legged OAuth apps are only compatible with the athena/service/MDP.* scope and system-level FHIR scopes. After selecting Confirm Scopes, your Preview OAuth credentials will be automatically approved for these scopes. If you later need to add or remove scopes, you can do so by returning to this page and clicking Edit Scopes.
  7. Now that you have Preview OAuth credentials with approved scopes, you can begin testing your solution in our sandbox environment. Refer to our instructions for sandbox testing and authorization documentation to access API endpoints using OAuth credentials.
  8. If you have validated your solution in Preview and would like to move on to Production, you will either need to contract for athenahealth Platform Services or, if your app is only using Certified APIs, request Production OAuth credentials via PlatformServicesSupport@athenahealth.com. If you are already an athenahealth Platform Services customer, download the Tech Spec form from the Use Cases tab (in the Developer Portal console under Applications > [Your app name] > Use Cases) and email your completed form to PlatformServicesSupport@athenahealth.com. The form will be used to discuss the scope of your integration with our Integration Design team before issuing you Production OAuth credentials.
  9. To obtain API access to an athenaOne customer's Preview or Production environment, you must obtain the signed authorization and consent of the healthcare organization. We will provide you with an online authorization and consent form for your app when issuing you your Production OAuth credentials (see previous step).
  10. Optional: If you wish to become a Marketplace Partner and list your app in athenahealth’s Marketplace, click Download the Marketplace Partner Document in the Marketplace tab and send your completed form to PlatformServicesSupport@athenahealth.com.

Create a 3-Legged OAuth personal health record (PHR) App

Follow the steps below to create a new personal health record (PHR) app supporting 3-legged OAuth:

  1. Log in to the Developer Portal console. The Applications screen will display any apps already registered to your account. Click (+) Create a New App.
  2. When prompted to choose your app category, select 3-Legged OAuth for PHR Apps and click Continue to App Details.
  3. Complete the required fields, including details on your app’s environment (Preview or Production), intended end users, OAuth client type, token authentication method, and redirect URLs. Review the required terms linked at the bottom of the page and click the checkbox to agree.
  4. Click Create Application to generate Preview or Production OAuth credentials for your app.
  5. Copy your app credentials and store them in a secure place. If your app has been provisioned a client secret, you will not be able to view the client secret again without rotating to a new one. Please note that rotating your client secret will invalidate the previous one and may result in breaking changes in your app until references to that client secret are updated.
  6. In your app’s dashboard, click on the Scopes tab and select the OAuth scopes to which you require access. Please note that PHR apps are only compatible with Certified API scopes corresponding to the app’s intended end users. After selecting Confirm Scopes, your OAuth credentials will be automatically approved for these scopes. If you later need to add or remove scopes, you can do so by returning to this page and clicking Edit Scopes.
  7. While your Preview and Production OAuth credentials are automatically granted access to all athenaOne customer environments, refer to our instructions for sandbox testing and authorization documentation to access API endpoints using OAuth credentials. We have also configured a dummy patient record and patient login credentials for PHR testing in Preview:

Practice ID: #80000

Patient ID: #14545

Email / Password (for Login with athenahealth): phrtest_preview@mailinator.com / Password1

  1. Optional: All PHR apps are required to be listed on athenahealth’s Marketplace as part of our compliance with the ONC’s 21st Century Cures Act information blocking provisions. Your PHR app will be listed within 5 days of receiving your Production credentials. If you wish to enhance your PHR app listing on the Marketplace, click Download the Personal Health Record Document in the Marketplace tab and send your completed form to PlatformServicesSupport@athenahealth.com.

Create all other 3-Legged OAuth Apps (non-PHR)

Follow the steps below to create a new 3-legged OAuth app. If you intend to use 3-legged OAuth to build a PHR app, refer instead to the instructions here.

  1. Log in to the Developer Portal console. The Applications screen will display any apps already registered to your account. Click (+) Create a New App.
  2. When prompted to choose your app category, select 3-Legged OAuth and click Continue to App Details.
  3. Complete the required fields, including details on your app’s intended end users, OAuth client type, token authentication method, and redirect URLs. Review the required terms linked at the bottom of the page and click the checkbox to agree.
  4. Click Create Application to generate Preview OAuth credentials for your app.
  5. Copy your app credentials and store them in a secure place. If your app has been provisioned a client secret, you will not be able to view the client secret again without rotating to a new one. Please note that rotating your client secret will invalidate the previous one and may result in breaking changes in your app until references to that client secret are updated.
  6. In your app’s dashboard, click on the Scopes tab and select the OAuth scopes to which you require access. Please note that 3-legged OAuth apps are only compatible with Certified API scopes and FHIR scopes corresponding to the app’s intended end users. After selecting Confirm Scopes, your Preview OAuth credentials will be automatically approved for these scopes. If you later need to add or remove scopes, you can do so by returning to this page and clicking Edit Scopes.
  7. If your app is a provider-facing app that will be launched from within athenaOne using the EHR SMART app launch sequence, you will need to email PlatformServicesSupport@athenahealth.com to have your app's launch URL configured in athenaOne. Please include your app name, launch URL, FHIR base URL (see here; must indicate if DSTU2 or R4 and global or site-specific), and athenaOne environment (Preview or Production) in the email body. Your request can optionally include a brief app description (max. 50 characters) and a public URL with your app's icon (scaled to Favicon-sized format of 16x16 pixels) to improve the experience for your app's end users in athenaOne. Refer to our Embedded Apps documentation for more information on SMART app launch from athenaOne.
  8. Now that you have Preview OAuth credentials with approved scopes, you can begin testing your solution in our sandbox environment. Refer to our instructions for sandbox testing and authorization documentation to access API endpoints using OAuth credentials. If your app is a patient-facing app, we have configured a dummy patient record and patient login credentials you can use for PHR testing in Preview (see below).  If your app is a provider-facing app, you will need access to a Preview athenaOne tablespace in which to test, either by entering into a business associate agreement with an athenahealth customer who is willing to test your solution in their Preview tablespace, or by contracting with athenahealth Platform Services. If you are an athenahealth Platform Services customer that requires Preview tablespace access, please contact PlatformServicesSupport@athenahealth.com for assistance setting up a Preview tablespace.

Practice ID: #80000

Patient ID: #14545

Email / Password (for Login with athenahealth): phrtest_preview@mailinator.com / Password1

  1. If you have validated your solution in Preview and would like to move on to Production, you will either need to contract for athenahealth Platform Services or, if your app is only using Certified APIs, request Production OAuth credentials via PlatformServicesSupport@athenahealth.com. If you are already an athenahealth Platform Services customer, download the Tech Spec form from the Use Cases tab (in the Developer Portal console under Applications > [Your app name] > Use Cases) and email your completed form to PlatformServicesSupport@athenahealth.com. The form will be used to discuss the scope of your integration with our Integration Design team before issuing you Production OAuth credentials.
  2. To obtain API access to an athenaOne customer's Preview or Production environment, you must obtain the signed authorization and consent of the healthcare organization. We will provide you with an online authorization and consent form for your app when issuing you your Production OAuth credentials (see previous step).
  3. Optional: If you wish to become a Marketplace Partner and list your app in athenahealth’s Marketplace, click Download the Marketplace Partner Document in the Marketplace tab and send your completed form to PlatformServicesSupport@athenahealth.com.
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