Best Practices

Storing App Secrets

The best practice for a Production deployment is to maintain the key and secret in a centralized place (a key server). The key server is responsible for calling the OAuth endpoint and getting and caching (until expiration) the access token. It should then make that token available for any callers in your environment who need to make an API call. You can store the key and secret in one place and can maintain a higher level of security there (for example, a smaller number of people able to log into that particular server).

For security reasons, we urge you not to check the key and secret into your codebase.

Secrets and JWKs are listed under Credentials tab of Apps listed in your Account Dashboard.

Typically, if you see "Developer Inactive" and a 401 response, it is because you are not passing the bearer token in the Authorization header with your call to an endpoint.

Reordering Keys in Message Payloads

Keep in mind that the order of keys in a message payload are unordered, so code should not be written that depends on the order of keys. Even if the keys appear to be ordered, upgrades to athenahealth's software may change the order of keys.

Daily Quotas

There are response headers returned upon each OAuth or API request for your convenience.  The headers may represent different meanings depending on the request context.  Below is a table detailing the differences: 

Request Context 



OAuth Request 


The limit of OAuth requests the app can make within a period of one minute. 

OAuth Request 


The number of remaining counts the OAuth API can be used within the minute before being rate-limited.  This count resets at the top of every minute. 

API Request 


The limit of API requests you can make in a period of one day. 

API Request 


The number of remaining counts the normal API can be used before being capped.  This count resets at midnight GMT. 

API Request 


An identifier associated with this request. 

Application Design

Limits and Offsets are used in APIs to help reduce the amount of results returned in API calls.  


Limits are used to return a subset of information. If we have a collection that returns a list of items, and the amount of those items is greater than the LIMIT input, we stop returning them after that amount. For example, if the items to be returned are IDs => [ 1,2,3,4,5,6,7,8,9,10 ] and we use a limit of 3, the output of the API would be IDs => [1,2,3].

Most fields in the patient API are limited to a maximum of 20 characters. There are a few exceptions to the 20-character limit:

Patient Field Limit
Field Name Character Limit
Lastname field   30
Address1/2   100
City, Guarantor City   30
State, Guarantor State   10
All Zips  10
SSN   13
Employer name   100
Contact name   50
Email 50
Employer city   40
Employer address   80
Name suffix   10


Offsets are used to return information from API calls starting at a specified value.  If more results are desired, you can use the OFFSET to get the next "page" of results. Using the same example above returning IDs => [ 1,2,3,4,5,6,7,8,9,10 ] we could use an offset of 3 and get IDs => [4,5,6,7,8,9,10,11,12,13].

Using the two in combination such as using a limit of 3 and an offset of 3 would return IDs => [4,5,6].

Note: Certain APIs have built-in default limits which necessitates the ability to handle them gracefully. 

Server Load Mitigation and Data Backfills

Data Backfills

As our community of users continues to grow, we are proactively working to ensure consistent API uptime with limited outage risk. As a result, we will not accept integrations that necessitate the import of bulk data from one system to another. We acknowledge that the onboarding period for a client might require a temporary period where basic practice data is collected to configure an integration; this is something we discuss with users during the development stage of every project. 

If your solution requires bulk retrieval of data, you must use one of the following:

  1. athenahealth Data View or other non-API solutions that are designed for these use cases.
  2. FHIR Bulk Export using Group resource. Note: Export duration varies by context size.

Call Volume & Filtering

The performance of the API is more about the amount of processing work needed to compile a response to each call, and less about the absolute number of calls made. This is something you will discuss with your assigned athenahealth technical lead during the integration project, but keep these guidelines in mind when putting together your initial documentation.

The following calls are particularly intensive on our system: 

  • GET /patients 
  • GET /appointments/booked 
  • GET /appointments/booked/multipledepartment
  • GET /claims 

We recommend a few different strategies for mitigating server load issues:

  1. Parameterizing GET calls when possible.
  2. Conducting larger data pulls during "off hours" (8pm - 6am EST).
  3. Building a throttling mechanism into your app to regulate the number of calls made. 
  4. Leveraging subscription endpoints to retrieve changed data. You can call changed data as often as once per minute. To read more about our subscription functionality, visit this page.

If your solution requires GET /appointments/booked, we will ask you to limit your call scope to a defined range of days before and after the appointment date. For claims, we recommend a range of 3-6 months of past data based on the parameters used to filter the call, and how often the call needs to be made. If your solution requires GET /patients, we will ask you to parameterize those calls or recommend that you use GET /patients/enhanced best match as an alternative. 

  • Note that this range will be more limited if you are not caching data. 
  • For enterprise clients, please reduce the scope of your data pull as much as possible. 

File Upload

When uploading documents, we suggest you follow our best practices:

  • Base 64 encoded
  • Content should be multi-part formatted
  • We suggest using .pdf for document upload
  • "attachmentcontents" should be no larger than 20MB for optimal API processing time

If image uploads still fail (especially for larger images) try base64 encoding, then URL encoding.

Handling Beta APIs

Some of the Beta APIs are rolled out for limited practices and are behind athenaOne rollout features. In other words, you may see some of these Beta APIs working for some practices in your App, but resulting in errors for a different set of practices. Expanding and rolling out the feature/Beta APIs to additional contexts are controlled by athenahealth and is an internal process. Our standard practice is to apply these rollouts globally once they have been confirmed to operate correctly without issues. Rollouts are no longer anything that users should need to worry about unless they are doing something with a new endpoint, in which case Marketplace Partners should contact their Partner Success Manager, and all other API users should work with a Customer Success Manager to submit an Integration Request.

If you need help understanding and debugging some API issues you are seeing, please feel free to review our additional reference documentation and workflow documentation. We are always happy to review and answer questions related to the functionality of an API. However, if you believe you have found an API bug in Production, please feel free to submit a support case through Success Community with specific examples and input parameters so a larger staffed team can review.

Application Security

Error Handling and Logging

1. Display Generic Error Messages 

  • Error messages should not reveal details about the internal state of the application. For example, file system path, user ids, and stack information should not be exposed to the user via an error message. 
  • Be careful with your approach to confirming whether or not data exists. For example, if you expose a way to perform a patient search (e.g. during patient portal registration), ensure that the error messages are generic and do not reveal whether a user is or is not a patient at that facility or with a particular provider group.  

2. Log Access to Sensitive Data and Store Securely  

  • Logs should be stored and maintained appropriately to avoid information loss or tampering by intruders.  
  • Any access to sensitive data should be logged. This is particularly important for corporations that have to meet regulatory requirements like HIPAA, PCI, or SOX. 
  • If applicable, any authentication activities, whether successful or not, should be logged. 

Data Protection

1. Use HTTPS everywhere (transmitting data securely) 

  • Ideally, HTTPS should be used for your entire application. If you have to limit where it’s used, then HTTPS must be applied to any authentication pages as well as to all pages after the user is authenticated. 

2. Implement a strong password policy and reset system (if not using SSO)  

  • If applicable, implement a policy that requires passwords to meet specific strength criteria during registration. 
  • In addition, any password reset option must not reveal whether or not an account is valid. This prevents username “harvesting.”  

3. Store user passwords securely (if not using SSO) 

  • If the app allows for password authentication (not utilizing athenahealth SSO), user passwords must be stored using secure hashing techniques with strong algorithms such as PBKDF2, bcrypt, or SHA-512. 

4. Limit the use and storage of sensitive data 

  • Conduct an evaluation to ensure that sensitive data elements are not being unnecessarily transported or stored. Where possible, use tokenization to reduce data exposure risks.  
  • Make sure that URLs posted to athenaOne do not contain exposed patient data that could be used publicly without authentication.  

5. Please use TLS 1.2 or higher  

  • TLS versions 1.0 and 1.1, as well as SSL versions 1.0, 2.0, and 3.0, are older protocols with known vulnerabilities that have been deprecated. 


1. Do not hardcode API credentials 

  • Never store credentials directly within the application code. While it can be convenient to test application code with hardcoded credentials during development, this significantly increases risk and should be avoided.  
  • We highly recommended that you do not check the key and secret into your codebase.  

2. Store API credentials securely  

  • The best practice for a production deployment is to maintain the key and secret in a centralized place (in this case a key server).  
  • The key server is responsible for calling the OAuth endpoint to retrieve and cache the access token (until expiration). It should then make that token available for any users in your environment who need to make an API call. 

3. Compliant Patient User Authentication for Surfacing PHI 

  • Surfacing PHI in places that do not require some form of authentication is considered a violation (ex.: a link that sends a user to a webpage with patient info).  
    • Also note that surfacing PHI to users that do not need that information can constitute a HIPAA violation.  
  • As mentioned earlier, revealing whether or not a patient exists in a practice (for example, Planned Parenthood or a substance abuse rehabilitation center) can constitute a PHI violation.  

Input and Output Handling  

1. Conduct contextual output encoding 

  • All output functions must contextually encode data before sending that data to the user.  

2. Validate the source of output (pulling data from athenaOne) 

  • Always ensure you are pulling the correct information (e.g. the correct appointment, patient, etc.)  

3. Validate the source of input (pushing data into athenaOne)  

  • Before submitting data into athenaOne, make sure that data has been validated and sanitized to maintain integrity. 
  • Take measures to ensure that duplicate patients are not being created if new patients are being pushed into athenaOne. 
  • Only practice users can decide to update the chart, not patients. 
  • For any patient-entered data, make sure a physician or clinician is reconciling this information. 
  • Please note that normally, documents will automatically appear in the clinical inbox for providers to review but can be set to bypass the clinical box and go straight into the patient chart. 

Access Control

1. Apply the principle of “least privilege”  

  • When an account is created, rights must be specifically added to that account to grant access to resources. 
  • Practices should not be allowed to access data belonging to other practices through the same MDP Partner unless explicitly agreed upon. 
  • A Vendor/Partner should not have access to a Client's athenaOne Preview/Production UI unless explicitly agreed upon by vendor/partner and client. 
  • Exposing PHI to users that do not need that information can constitute a HIPAA violation.  

2. Do not use unvalidated forwards or redirects 

  • Avoid using simple/naked URLs that can allow an attacker to access private content without authentication. 

Session Management

1. Re-generate access tokens  

  • Tokens should be regenerated when the user authenticates to the application and/or when the user privilege level changes.  
  • As a reminder, tokens need to be refreshed every hour.  

2. Implement an idle session timeout 

  • When a user is not active, the application should automatically log the user out.  

3. Implement an absolute session timeout  

  • Users should be logged out after an extensive amount of time (e.g., 4-8 hours) has passed since they logged in. This helps mitigate the risk of an attacker using a hijacked session.  

4. Place a logout button on every page 

  • The logout button or logout link should be easily accessible to users on every page after they have authenticated. 
  • When the user logs out of the application, the session and corresponding data on the server must be destroyed.  

5. Set the cookie expiration time  

  • The session cookie should have a reasonable expiration time. Non-expiring session cookies should be avoided. 

Configurations and Operations

1. Client requests to run reports of data not accessible via API 

  • Generally, if this data cannot be pulled via API, there is a valid reason for it (i.e. Medications or Insurances Packages are proprietary). 
  • There are many cases in which it is acceptable and risk-free to run a report for a client, but to be safe, all API-related reports should always be reviewed by Compliance.  

2. Be aware that some of our endpoints are more computationally intense than others and thus subscription endpoints should be considered 

  • GET /patients vs. GET/patients/search endpoint 
    • If possible, users should leverage GET /patients/search (if they want athenaOne type patient searching) or GET /patients/enhancedbestmatch 
  • GET Appointments/booked vs. GET appointments/changed endpoint  
    • The changed endpoint should be used to pull updates to the schedule rather than pulling all booked appointments every day.  
    • The booked endpoint should be used at the start of the week  
  • If you are approved to conduct large data pulls (e.g. GET /patients or GET /appointments/booked), these should be done during “off hours” (9PM - 8AM EST). We may also recommend that you implement call throttling to reduce additional risk.

Additional Notes

Throughout the build and eventual validation of a solution, the following issues should be proactively addressed: 

1. User Authentication for Surfacing PHI: 

  • Concern: Surfacing PHI to incorrect patients, etc 
  • Workflow/ API Solutions: 
    • Registration and log-in with 2-factor authentication (text/email). This should be in accordance with the regulations established by the relevant state, etc. 

2. Patient Matching Safety/Compliance: 

  • Concern: Duplicative patient entry or updates to incorrect patient charts  
  • Workflow/API Solution: To match patients, be sure to pass at least 4 input parameters 
    • Required Parameters: First name, Last name, DOB, fourth parameter: email, phone number, Zip Code, SSN, etc
  • Relevant API Calls: 
    • GET/POST/PUT /patients 
    • GET /patients/search 
    • GET /patients/enhancedbestmatch 

3. Security Compliance: 

  • Concern: clientid/secret storage 
  • Solution: Maintain your athenahealth clientid and secret in a centralized place (a key server) for a higher level of security and restrict the number of people who can access the key/server.   
  • Do not check the key/secret within any codebases. 
  • Never send bearer tokens, keys, and secrets over unencrypted email.  

4. API Call Limitations: 

  • Concern: Placing too many API Calls outside of the limitations, compromises all of athenaOne
  • Solution: Adhere to pre-established limitations: 
    • Preview Environments: (path: /preview1) 5 calls/second; 50000/day 
    • Production Environments (path: /v1) 100/sec, 500000
  • Utilize subscription endpoints
  • Limit large data pulls
  • Relevant API Calls: 
    • All calls, especially: GET /patients GET /booked/open/appointments

5. Updating Patient Chart Information 

  • Concern: Only athenaOne practice users can update the chart. Patients cannot update their chart information. 
  • Solution: Utilize and post Health History Forms or CCDAs as those initiate reconciliation task 
  • Relevant API Calls: 
    • Discrete data points within a patient’s chart like:
    • POST /chart/{patientid}/vitals /preview1/:practiceid/chart/:patientid/vitals 
    • POST /chart/{patientid}/problems 
    • /preview1/:practiceid/chart/:patientid/problems 
    • POST /chart/encounter/{encounterid}/diagnoses 
    • /preview1/:practiceid/chart/encounter/:encounterid/diagnoses 

Lack of compliance and proactive integration of the aforementioned solutions, along with any other issues, will result in a failed Solution Validation, along with the reassessment of the solution.

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

On this Page