1. Getting Started

Overview

This page is a step by step guide for connecting to this reference implementation. All the details needed to get started are on this page. If you run into any issues please reach out to Corey Spears on Zulip or submit an issue via the GitHub issue tracker.

Important URLs

Title	URL
FHIR Base	https://davinci-drug-formulary-ri.logicahealth.org/fhir
Metadata	https://davinci-drug-formulary-ri.logicahealth.org/fhir/metadata
Smart Configuration	https://davinci-drug-formulary-ri.logicahealth.org/fhir/.well-known/smart-configuration
Debug log	https://davinci-drug-formulary-ri.logicahealth.org/fhir/debug/Log
Registered Clients	https://davinci-drug-formulary-ri.logicahealth.org/fhir/debug/Clients
Registered Users	https://davinci-drug-formulary-ri.logicahealth.org/fhir/debug/Users

Connecting

Unauthenticated Access

The unauthenticated API supports reading the server capability statement (metadata), smart configuration, InsurancePlan, Basic, MedicationKnowledge and Location endpoints without authentication.

Authenticated Access

The authenticated API supports the SMART on FHIR App Launch Framework "standalone launch" workflow. This workflow supports user-facing client applications launched by a user to access the authenticated Drug Formulary API and requires a user to give explicit permission for their registered client application to use their user account for authentication purposes when using authenticated access.

A client must go through three steps before reading patient's related data (Patient and Coverage endpoints).

1. CLIENT REGISTRATION

   This is a "one-time", manual and straigh forward step. It enables the API to pre-authorize and curate clients that will be using the authenticated access. You can register your client through the web interface provided at /oauth/register/client endpoint. Submit your redirect uri and you will be assigned a client id and client secret. Please note this table is purged every time an update to the server is pushed (which can happen at anytime - especially during Connectathons). Before using the server please check your client is still registered. You can see a list of all clients currently registered here.

   The registration web interface uses the underlying POST requests described below:

   POST [base]/fhir/oauth/register/client

   Query Parameter:

   Parameter	Value
   redirect_uri	The redirect URI the client will use.

   Query Example:

   POST HTTP/1.1
   https://davinci-drug-formulary-ri.logicahealth.org/fhir/oauth/register/client?redirect_uri=http://localhost:4000/login
   

   Response:

   The response to the post is 201 CREATED on success with the (example) json body:

   {
     "id": "a12c5a8a-0288-4502-9190-5ddf79145938",
     "secret": "N3MXICwdkqIbbkhociXxtZJ8HGu4EpHKT7X7IA6M08P1m3px7aIfBDnfdStUfjArJGqQIoWtH4my5XtkZJso9SHSuOlkhcnIqfB8zj6PqVoXbqjt6svPaCtmDR0qiCZq0g8FfqAikI5DbUkKY2LomIwLjx3Qhe7nzuOZgeap4rDU959tHqYpaD11Yvgjk2SfRXZpdkcEURMhsLVvX7AXgsbylaVyy52iwsF8nSNfjtMXenDQhj1Jxr0WlZHisQNQ",
     "redirect": "http://localhost:4000/login"
   }

2. AUTHORIZATION

   Registered clients will go through an authorization process to obtain an access token that will be used to authenticate secured API requests. The process is described in detail in the SMART on FHIR specification. The process is as follow:

   1. The client sends a GET request to /oauth/authorization endpoint, which cause the app to redirect to the server's authorization endpoint and require the end-user to login.

      Query Parameters:

      Parameter	Value
      response_type	code
      client_id	The client id
      redirect_uri	The URI to redirect to with the code
      scope	The SMART on FHIR Access Scope
      state	Unique ID generated by the client for this interaction
      aud	The fhir base URL for this server

      Request Example:

      GET https://davinci-drug-formulary-ri.logicahealth.org/fhir/oauth/authorization?response_type=code&
            client_id=user689&redirect_uri=http://localhost:3000/index&
            scope=patient/*.read&state=12345abc&aud=https://davinci-drug-formulary-ri.logicahealth.org/fhir
      

   2. Once the client submits the GET request to the authorization endpoint, the user will be prompted to login. The following is the test user credentials you can use for testing:

      username: PDexPatient
      password: password
      

   3. Once the end-user has authorized the request, the server will redirect back to the application using the redirect_uri given upon registration with the authorization code provided as a parameter.

      Response parameters:

      Parameter	On	Value
      code	Success	The authorization code for the client
      state	Success	Echo of state parameter in the request
      error	Failure	Error code defined in RFC 6749

      Response Example:

      HTTP/1.1 302 Found
      Location: http://localhost:3000/index?code=abc123&state=12345abc
      

      Note: The authorization code is only valid for 2 minutes.

   4. The client app retrieves the authorization code and use it to get an access token by issuing a POST request to the server's token endpoint (/oauth/token) following the authorization_code OAuth 2.0 grant flow process, and including a basic Authorization header with the value base64Encode(client_id:client_secret) and use Content-Type of application/x-www-form-urlencoded. Request

      POST https://davinci-drug-formulary-ri.logicahealth.org/fhir/oauth/token
      

      Request Headers:

      Authorization: Basic MTpwYXNzd29yZA==
      Content-Type: application/x-www-form-urlencoded
      

      Request Body

      code: <AUTHORIZATION_CODE>,
      grant_type: authorization_code,
      redirect_uri: <CLIENT_REDIRECT_URI>
      

      Response Body

      The successful response will be a JSON object containing the access_token, token_type, expires_in, patient, scope, and refresh_token.

      {
          "access_token": "{signed JWT token}",
          "token_type": "Bearer",
          "expires_in": 3600,
          "patient": "{the user's patient id}",
          "scope": "{the server's supported scopes}",
          "refresh_token": "{signed JWT token}"
      }

      The access token token will only be valid for an hour.

3. AUTHENTICATION

   In all subsequent requests to the server for patient access, the client app must add the Authorization: Bearer {access_token} header to the HTTP request to authenticate the user.

   For testing purposes an admin token is available for clients that do not support this workflow yet. The admin token is

   eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2RhdmluY2ktZHJ1Zy1mb3JtdWxhcnktcmkubG9naWNhaGVhbHRoLm9yZy9maGlyIiwiaWF0IjoxNjQ1MTMzNDU0LCJleHAiOjE3Mzk4Mjc4NTQsImF1ZCI6Imh0dHBzOi8vZGF2aW5jaS1kcnVnLWZvcm11bGFyeS1yaS5sb2dpY2FoZWFsdGgub3JnL2ZoaXIiLCJzdWIiOiJhZG1pbiIsInBhdGllbnRfaWQiOiJhZG1pbiJ9.cLvTTpGH5lxXMjwsPN-1NPo9jUuc6C43FcjH8s81VA5kXdmRdQhAww2oO_i_IOTUnOVaIU-JU9Ygd3MBXckPnVlrLiN_Dtdb_71DcqpVJflc9FAqorcUGmaE5qg-nZVI_sKofPaliYxUeBriTgwS06VtILl2k2WylAD83LbDjBCCq4MBHlaWSCqc9LRKJT3Ez3D93IPWgwBgPT46cIML6_PdwLO5Zl5XkEyXLjsUUAuraPM-dET7tw6KLr0gbd6Xdj2BuZLZjYmxTOWry_n6hAiQDTQ2iaLtwp2rtZlfbX5L38cpri-TRKN1l7EeNguJXk1dVfPPv78_5qqhqg71jQ
   

   Example Request with access token:

   GET {base url}/Coverage?
   patient={logged in user's patient id}
   &type=http://terminology.hl7.org/CodeSystem/v3-ActCode|DRUGPOL
   

   Request Headers:

   Authorization: Bearer { access_token }
   Content-Type: application/json
   

Testing

A postman collection is provided to test the server's endpoints and functionalities.