Skip to main content

Authentication & Authorization

NextGen Patient Access API Authentication Guide

Patient API OAuth2 Authentication​

R4 Patient API (FHIR R4) Authentication Endpoints & Data Route Base URLs:​

DSTU2 Patient API (FHIR DSTU2) Authentication Endpoints & Data Route Base URLs:​

Note: Patient Access API Route endpoints and usage details are documented in both the Developer Portal (in the API Explorer tool accessed via API Hub) and in the API-specific “Swagger” JSON available here (Note: Use the drop-down in the upper right of the Swagger UI to toggle between DSTU2 & R4 API documentation.)

Both the DSTU2 and R4 versions of NextGen Patient Access APIs support the following OAuth 2.0 Grant Types; usage examples follow.

Authorization Code Grant (grant_type=authorization_code)​

Refresh Token Grant (grant_type=refresh_token)​

Note: YOUR_CLIENT_ID and YOUR_CLIENT_SECRET are issued provisionally upon requesting an application in the NextGen API Developer Portal, and become active only when your request to "Add Application" (as detailed in the How to Register & Configure Your Application document) is approved by a NextGen Administrator.

Obtaining a Patient API Token via Authorization Code Grant​

  • Patients will login via your redirect page, which will result in the creation of an authorization code your app will then exchange for an access_code at the POST /token auth endpoint.
  • To begin, your app will need to launch a browser frame/window so the patient can enter their Patient API credentials.
  • The initial Call from your app to display the NextGen Patient API login UI for the Authorization Code Grant is shown below.

Example Patient API Authorization Call Using Authorization Code Grant​

  • The patient enters their Patient Access API credentials (created via the Patient API Enrollment Workflow process, which is facilitated by the patient's NextGen Practice) and authenticates.
  • The authorization code issued under the grant must then be POSTed to the /token endpoint with the parameters & headers shown below, and the token is returned in response.
  • Please note the required application/x-www-form-urlencoded Content-Type header.

Request to Token (after obtaining the Authorization Code):​

(Note: The FHIR R4 data path is shown in the example for this endpoint)

Obtaining a Refresh Token via Refresh Token Grant​
  • The FHIR DSTU2 and FHIR R4 Patient APIs both support refresh tokens.
  • You can exchange a refresh token for a new access token via the /token endpoint by changing the grant_type to equal refresh_token and adding a refresh_token query parameter and value as shown in the following examples.
  • Refresh Tokens must be exchanged within 48 hours of issue.

Refresh Token Grant Request Example (DSTU2 endpoint shown):

curl -X POST \
 'https://fhir.nextgen.com/nge/prod/patientoauth/token?grant_type=authorization_code&redirect_uri=https://YOUR_CALLBACK_URL
&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&code=ISSUED_CODE' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
GET https://fhir.nextgen.com/nge/prod/patientoauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID
&redirect_uri=https://YOUR_CALLBACK_URL

Note: The Refresh Token examples below use inconsistent endpoints to illustrate the differences in the base URL between the DSTU2 and R4 versions of Patient API. Your app's use of base URL must be consistent for success with the Patient API version you elect to use.

curl -X POST \
 'https://fhir.nextgen.com/nge/prod/patientoauth/token?grant_type=refresh_token&refresh_token=REFRESH_TOKEN_VALUE&client_id=
YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET' \
 -H 'Content-Type: application/x-www-form-urlencoded' \

Subsequent Patient API Call (R4 endpoint shown):​

curl -X GET \
 https://fhir.nextgen.com/nge/prod/fhir-api-r4/fhir/r4/Patient \
 -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
 -H 'Accept: application/json'
  • The "id" in the response payload returned by the GET /patient route in the example above will be the patient ID required as a query parameter in many other routes in the Patient API set.
  • The route-level documentation includes details specifying the routes that will expect this Patient ID value as the value for the {patient} query parameter (which is required by most Patient API routes).
  • The same {id} value returned by GET /Patient is also expected as the {id} path variable for the GET /Patient/{id} route.

How to Make Patient Access API Calls​

  • The Patient Access APIs (named FHIR DSTU2 & FHIR R4) enable patients to access their data using compatible applications as required by various regulations.
  • After having obtained your app’s client_id & client_secret (provided upon completion of the process documented in How to Register & Configure Your Application), your app will be able to obtain an authentication token and use the token to make subsequent data requests on behalf of the authenticated patient.
  • Your app may also use the refresh_token grant to obtain a new access_token), provided you exchange the refresh_token for a new access_token within 48 hours of the initial issue of the refresh_token.
  • The access_token is required to make any & all Patient Access API calls, excepting calls to the OAuth endpoints and to the GET /metadata conformance routes.

Testing Notes:​

  • If you are using another tool such as Postman, the base URL variant (either DSTU2 or R4) from the top of this document) you use to make data calls will invoke the corresponding version of Patient Access API. Use the Authentication Grant detailed in the prior section to obtain an access_token.
  • Remember, the API(s) named FHIR DSTU2 and/or FHIR R4 must have first been added to your app in the Developer Portal as described in the How to Register & Configure Your Application document prior to success.
  • Upon obtaining an access_token for either version of Patient API, you can proceed to making data calls to individual Patient API routes documented in the conformance (GET /metadata) route response and in the online Patient Access API Documentation. The Base URLs are unique to each FHIR version; please consult the lists of Authentication & Data Route Endpoints in the prior Patient API OAuth2 Authentication section as needed.
  • Additional guidance is available in the Patient Access API FAQ

Expected Headers​

Always ensure your GET calls to data endpoints include the following header values:

Patient API Sandbox Credentials​

The following Patient API credentials (also shown in prior examples) are valid for testing both versions of Patient API (nge.prod.fhir-api & nge.prod.fhir-api-r4):

  • Sandbox Username: patientapitest
  • Sandbox Password: Password1!

Reference:​

https://www.nextgen.com/-/media/files/api/nge-patient-api-auth-guide.pdf