Authorization

Systemedx XNet API is secured by XNet Auth, an OAUTH 2.0 authorization server.
App developers that register with XNET are issued OAuth client credentials used to request access tokens (a type of JSON web token, JWT) from our authorization server.
An access token represents an app’s authorized access to one or more API endpoints used to read, write, or update data in the API, where an app is required to provide an access token to make a successful request to those endpoints.

The following authorization methods are supported in XNet API:

2-legged OAuth, in which apps use their OAuth client credentials to obtain an access token. This method is used where XNet users have authorized an app to access a specific set of endpoints for their organization. Our implementation of 2-legged OAuth uses the client credentials grant type as defined by OAuth 2.0.
3-legged OAuth, in which apps must get end user authorization to obtain an access token, in addition to providing their client credentials. This method is used for patient- and provider-facing apps accessing data on behalf of an end user. Our implementation of 3-legged OAuth uses the authorization code grant type as defined by OAuth 2.0.

Supported Scopes

Below are the supported scopes (or permissions) by our API. Access for the individual scopes can be requested/granted during user registration. Scopes indicated below are represented by "r" for Read and "s" for Search functionality. Items with "rs" have both scopes supported but a patient/user may have access granted to only one or the other.

Patient-Specific Scopes

Patient-specific scopes allow access to specific data about a single patient. Which patient is not specified here: clinical data scopes are all about what and not who which is handled in the next section. Patient-specific scopes start with patient/. Note that some EHRs may not enable access to all related resources (for example, Practitioners linked to/from Patient-specific resources). Note that if a FHIR server supports linking one Patient record with another via Patient.link, the server documentation SHALL describe its authorization behavior.

patient/AllergyIntolerance.rs
patient/CarePlan.rs
patient/CareTeam.rs
patient/Condition.rs
patient/Device.rs
patient/DiagnosticReport.rs
patient/DocumentReference.rs
patient/Encounter.rs
patient/Goal.rs
patient/Immunization.rs
patient/Location.rs
patient/Medication.rs
patient/MedicationRequest.rs
patient/Observation.rs
patient/Organization.rs
patient/Patient.rs
patient/Practitioner.rs
patient/PractitionerRole.rs
patient/Procedure.rs
patient/Provenance.r
patient/Binary.r
patient/*.rs

User-Level Scopes

User-level scopes allow access to specific data that a user can access. Note that this isn’t just data about the user; it’s data available to that user. User-level scopes start with user/.

user/AllergyIntolerance.rs
user/CarePlan.rs
user/CareTeam.rs
user/Condition.rs
user/Device.rs
user/DiagnosticReport.rs
user/DocumentReference.rs
user/Encounter.rs
user/Goal.rs
user/Immunization.rs
user/Location.rs
user/Medication.rs
user/MedicationRequest.rs
user/Observation.rs
user/Organization.rs
user/Patient.rs
user/Practitioner.rs
user/PractitionerRole.rs
user/Procedure.rs
user/Provenance.r
user/Binary.r
user/*.rs

System-Level Scopes

System-level scopes describe data that a client system is directly authorized to access; these scopes are useful in cases where there is no user in the loop, such as a data monitoring or reporting service. System-level scopes start with system/.

system/AllergyIntolerance.r
system/CarePlan.r
system/CareTeam.r
system/Condition.r
system/Device.r
system/DiagnosticReport.r
system/DocumentReference.r
system/Encounter.r
system/Goal.r
system/Immunization.r
system/Location.r
system/Medication.r
system/MedicationRequest.r
system/Observation.r
system/Organization.r
system/Patient.r
system/Practitioner.r
system/PractitionerRole.r
system/Procedure.r
system/Provenance.r
system/Binary.r
system/*.r
system/*.d - for Delete rights

Token Request

Input Parameters

The app issues an HTTP POST to the EHR authorization server’s token endpoint URL. For more info, visit the following site.

* = required

Parameter	Type	Value
grant_type*	string	For 2-legged OAuth, the value is always client_credentials. For 3-legged OAuth, the value will be either authorization_code to initially request an access token, or refresh_token to obtain a new access token from a refresh token.
redirect_uri	string	The same redirect_uri used in the initial authorization request.(Required if grant_type is authorization_code)
code	string	Code that the app received from the authorization server. (Required if grant_type is authorization code)
code_verifier	string	This parameter is used to verify against the code_challenge parameter previously provided in the authorize request. (Required for token authentication using PKCE if grant_type is authorization_code)
refresh_token	string	Required if grant_type is refresh_token. The value is the refresh token returned by the authorize endpoint.
scope	string	This is required if the grant_type is client_credentials or refresh_token. The value is a space-delimited, case-sensitive string of the requested scopes. If the grant_type is a refresh_token, then the requested scopes must be a subset of those provided when the refresh token was originally created.
client_id	string	Required for public apps. Omit for confidential apps.

Output Results

Parameter	Description
access_token	The access token (JWT) issued by the authorization server
token_type	describes the access token; value is always “Bearer”
expires_in	Lifetime in seconds of the access token, after which the token SHALL NOT be accepted by the resource server
scope	Scope of access authorized. Note that this can be different from the scopes requested by the app.
id_token	Authenticated user identity and user details, if requested
refresh_token	Token that can be used to obtain a new access token, using the same or a subset of the original authorization grants

Token Refresh

A Refresh Token is returned by the authorize endpoint when the offline_access scope is requested and obtained with the user’s authorization. To get an access token from a refresh token, you will need to form a new token request providing the refresh token in the refresh_token parameter and refresh_token as the value for the grant_type parameter. An app will also need to specify in the scope parameter which of the previously granted scopes your app would like included in the new access token.

PKCE Implementation

Token authentication using Proof Key for Code Exchange (PKCE) is required by our authorization server for apps that cannot securely store a client secret. PKCE is a specification to the OAuth 2.0 Authorization Code Flow that requires your app to generate its own secret for each token request (called a “code verifier”) that can be verified by the authorization server (using a transformed value of the code verifier called a “code challenge”, which is passed in the authorize request along with the transformation method, or “code challenge method”). The code challenge and code challenge method must be provided in your app's authorize request and the code verifier sent in the token request. For more information on PKCE, please visit the following link