Please read before you proceed
- This documentation is targeting OpenEMR version 7.0.2
- This guide is intended for experienced technical professionals who are familiar with OpenEMR and custom HTTP requests. The information provided here is for example purposes only. We do not provide any warranty or assume any responsibility for the actions taken based on this guide. Proceed with caution and ensure you understand the implications of the steps described.
Step 1: Configuration
- In your OpenEMR dashboard visit Admin > Config > Connectors and check ☑️ the following options:
-
- “Enable OpenEMR Standard REST API
- “Enable OpenEMR Patient Portal REST API (EXPERIMENTAL)”
- Click Save at the bottom of the page.
Step 2: Create an application
Register the application
Why do you have to do the following steps?
Unfortunately the Admin > System > API Clients is not working properly when creating apps and is not up to date with the required scopes in the available scope list. The following guide is for experienced users.- Visit OpenEMR and open your browser console (Right Click > Inspect) and select the “Console” tab on your inspector. Substitute the {{ address }} part of the script below with your OpenEMR address. For example, if you address is https://openemr.acme.com/emr then fetch URL should be https://openemr.acme.com/emr/oauth2/default/registration
(await fetch("https://{{address}}/oauth2/default/registration", {
"credentials": "include",
"headers": {
"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:130.0) Gecko/20100101 Firefox/130.0",
"Accept": "*/*",
"Accept-Language": "en-US,en;q=0.5",
"Content-Type": "application/json",
"Sec-Fetch-Dest": "empty",
"Sec-Fetch-Mode": "cors",
"Sec-Fetch-Site": "same-origin",
"Priority": "u=0",
"Pragma": "no-cache",
"Cache-Control": "no-cache"
},
"referrer": "http://localhost/interface/smart/register-app.php",
"body": JSON.stringify({
"application_type": "private",
"redirect_uris": [ "https://api.us-east-1.keragon.com/rest/auth/callback" ],
"initiate_login_uri": "",
"post_logout_redirect_uris": [ "" ],
"client_name": "Keragon",
"token_endpoint_auth_method": "client_secret_post",
"contacts": [ "" ],
"scope": "openid offline_access api:oemr user/appointment.read user/appointment.write user/facility.read user/facility.write user/insurance.read user/insurance.write user/insurance_company.read user/insurance_company.write user/insurance_type.read user/list.read user/patient.read user/patient.write user/practitioner.read user/practitioner.write user/prescription.read",
"jwks_uri": "",
"jwks": ""
}),
"method": "POST",
"mode": "cors"
})).json();
- The result in the console should contain the client ID and client secret. See screenshot:
- Keep the client ID and secret for later use.
Enable the registered app
- After successful creation of the app visit Admin > System > API Client and the newly created application should be available. The client name should be the one provided in the request where the client ID should be the one on the response (remember to keep both ID and secret from the response).
- Ensure your application is enabled. Enable the application by Clicking “Edit” and enabling the app from the up right corner (if enabled only disable action would be available).
Step 3: Create the authentication in Keragon
- Visit https://app.keragon.com/authentications/new/ and search for “OpenEMR”.
- Add your OpenEMR URL in the OpenEMR Base Domain. Ensure the full URL is copied including the ending `/` character e.g. https://openemr.acme.com/emr/
- Add client ID and secret as found in the app registration response from the previous step.
- Click Connect
You should be redirected to the OpenEMR OAuth 2.0 flow and login with the user that has access to perform relevant operations such as create patient, create appointment etc.
After successful login a new authentication should have been created in Keragon dashboard.