FHIR 4.0 API Documentation
Introduction
Fast Healthcare Interoperability Resources, or FHIR, is a standard way of defining an API for healthcare resources. More information can be found at the FHIR website. You also must agree to TERMS OF SERVICE
Registration
Developers wishing to integrate with the API must contact the PHI Provider that uses Veracity as their EMR. Each Provider is considered a separate entity and will have their own Registration URL. Each Provider is responsible for maintaining the rights of API accounts). Once a Provider decides to grant access to you as a third-party developer, they will provide you with a registration link. The provider then is tasked with approving or denying your registration. The fhir base URL and oauth2 server URL are the same for every provider. Once a link is provided, you need to fill out the registration form. Once submitted, the PHI provider can then approve or deny. Once approved you will receive an OAUTH client_id and if applicable client_secret to use on subsequent requests following the protocols specified in the official SMART App Authorization Guide.
Confidential clients, such as web apps, which are capable of securely storing credentials will be issued a client_secret that may be used in conjunction with the client_id to form an authorization grant, which can be used to obtain refresh and access tokens. Our refresh tokens are long-lived and conform to Health IT criteria documented here.
Public applications, such as native apps, which are incapable of securely storing credentials will not be issued a client_secret. Instead, the authorization_code grant flow will be used to issue refresh tokens. As recommended in the OAuth 2.0 Authorization Framework spec (RFC 6749).
Security
Prior to making API requests, the client application must obtain an Access Token from the OAUTH Server. The client software must support OAuth 2.0 authorization code grant or client credentials grant flow for public clients as detailed in RFC 6749.
For confidential client applications using authorization code grants, end user authentication is performed using a username and authentication credentials provided by the PHI provider. A healthcare organization may reuse existing patient portal or EHR credentials for this purpose, in which case the authenticated username maps to a unique patient portal user or EHR user. The end user should obtain these credentials directly from the PHI provider from which they wish to access data.
When an end user is directed to the authorization endpoint, the user will be presented with a login screen where they can enter their credentials for the healthcare organization they are accessing. If the correct credentials are supplied and the end user grants access to the client application, an authorization code will be returned to the client that the client application can use to obtain an access token through the token endpoint as described in RFC 6749.
The complete OAuth 2.0 endpoint URLs for a given FHIR endpoint are published in the FHIR URL well known SMART configuration endpoint, as per Section 4 of the HL7 SMART App Launch specification.
Refresh tokens: Client apps that use the authorization code flow and can securely store refresh tokens may request a refresh token by including the offline_access scope in the initial authorization endpoint request. Note that the end user may remove this scope during the authorization process. If a refresh token is permitted, it will be returned together with the access token as per RFC 6749, and can be exchanged for a new access token as per RFC 6749. Refresh token lifetime defaults to 90 days. Each refresh token may be used once; a replacement refresh token will be issued when the client app uses a valid refresh token to obtain a new access token. Note that refresh tokens are not issued to Client apps that support client credentials code flow as these clients can authenticate directly to the token endpoint to obtain a new access token.
PKCE support: Proof Key for Code Exchange (PKCE) as defined by RFC 7636 is supported for Client apps that use the authorization code flow. The use of PKCE by such clients is required. Client apps must use only the S256 code challenge method. Please refer to RFC 7636 for details on how to use PKCE in requests to the authorization and token endpoints.
All requests to the API must include the access token transmitted in the Authorization header of the HTTP request as a bearer token as illustrated in RFC 6750. If the access token is missing, expired, or otherwise not valid for the requested operation, the API will return a 401 Unauthorized or 403 Forbidden response.
Resources
Resources can be found at FHIR REST API Swagger.
Errors & Exceptions
If the access token used in the request is invalid, expired, or the user has not been authorized to access the requested Resource, the API will return a 401 Unauthorized or 403 Forbidden HTTP response.
If the request cannot be processed for other reasons (temporarily unavailable, unsupported resource type, system error, etc.), the API will return a 400 Bad Request HTTP response containing an OperationOutcome Resource with additional information regarding the issue contained in the OperationOutcome.issue element.
Handling of OAuth-related errors is detailed in RFC 6749.