API Keys

API keys let your own systems and third-party integrations call Avon's APIs. When you create a key, you choose exactly which types of data it can read, write, or delete, so each integration only gets the access it needs.

For details on how to use a key once it's created, check out our API documentation.

Prerequisites

Part 1: Global admin access (EMR)

Only global admins can create, view, and revoke API keys. If you don't see "API Keys" under the Organization section in Settings, ask a global admin in your organization to create the key for you or to make you a global admin.

Follow the instructions here to learn more about admin roles.

Steps

Step 1: Name the API key (EMR)

To start creating an API key:

• Go to the EMR (e.g. emr.avonhealth.com)
• Click on the hamburger menu on the top left corner > Settings > API Keys (under Organization)
• Under "Create New API Key", enter a Key Name. Use a name that tells you which integration uses the key (e.g. "Scheduling sync" or "Data warehouse export").

Step 2: Choose what the key can access (EMR)

Under "Data Access", choose one of the following:

Option 1: Full access

• Check "Full access"
• The key can use every data type in the table, plus any data types and endpoints Avon adds in the future
• Only use full access for integrations you fully trust and control

Option 2: Scoped access

Leave "Full access" unchecked and pick permissions per data type in the table. Each row is a type of data (e.g. Patients, Appointments, Notes, Insurance claims) and each column is a permission:

• Read: View and list records of this type.
• Write: Create and update records of this type.
• Delete: Delete records of this type.
• Other: A sensitive action that has its own permission, so that Write alone never grants it. For example, "Sign" for notes, care plans, and documents, "Submit" for lab orders, and "Submit to payers" for insurance claims.

A few things to keep in mind when choosing permissions:

• Every permission includes Read. Checking Write, Delete, or an Other action on a row also checks Read for that row, and unchecking Read clears every permission on that row.
• Click "Read", "Write", or "Delete" in the table header to select or clear that permission for every row at once.
• Not every data type has every permission. If a checkbox is missing, that permission isn't available for that data type (for example, Slots and FHIR resources are read only).

All data types and permissions

These are all the data types you can scope a key to, in the order they appear in the table, and the permissions available for each:

Step 3: Create the key and save the credentials (EMR)

• Click "Create API Key". The button stays disabled until the key has a name and either "Full access" or at least one permission is selected.
• An "API Key Created" modal will pop up with the key's Client ID and Client Secret
• Click the copy button next to each value and store them somewhere secure, such as a password manager or your integration's secrets store

Note: The client secret is only shown once. If you close the modal without copying it, you'll need to revoke the key and create a new one.

• A Postman environment file for the new key is also downloaded automatically, so you can start testing requests in Postman right away
• Click "Done"

Step 4: View existing API keys (EMR)

All keys are listed under "Existing API Keys" on the same page. Each key shows:

• Name and Client ID
• Access: Either a "Full access" tag, or one tag per data type listing its permissions (e.g. "Notes: read, write, sign")
• Created date, and the Revoked date if the key has been revoked

Note: API keys created before scoped access was added have full access, since they were created before scoping. They show a "Full access" tag.

To download the Postman environment file for a key again, click the "Postman" button next to it.

Step 5: Revoke an API key (EMR)

Revoke a key when an integration is retired, when the key may have been exposed, or when you need different permissions (a key's permissions can't be edited after it's created, so create a new key with the right access and revoke the old one).

• Go to the EMR (e.g. emr.avonhealth.com)
• Click on the hamburger menu on the top left corner > Settings > API Keys (under Organization)
• Click the "Revoke" button next to the key
• Click "Revoke" in the confirmation modal

Note: Any integration using the key stops working immediately. This can't be undone. Revoked keys stay in the list with a "Revoked" tag so you have a record of them.