Authenticating with FHIR Server using OAuth2 Client Credentials

This document outlines the process for authenticating with the b.well FHIR server at fhir.icanbwell.com using the OAuth2 Client Credentials flow. This flow is typically used for server-to-server communication where a client application needs to access protected resources on behalf of itself, rather than a specific end-user.

Prerequisites

Before you begin, ensure you have the following:

• Client ID: A unique identifier for your application, provided by b.well.
• Client Secret: A confidential secret key associated with your Client ID, also provided by b.well. Keep this secret secure.
• FHIR Server Base URL: The base URL for the b.well FHIR server, which is https://fhir.icanbwell.com.

Obtaining an Access Token

To obtain an access token, you will make a POST request to the b.well FHIR server's OAuth2 token endpoint. The token endpoint must be discovered via the well-known configuration endpoint.

Well-Known Configuration Endpoint

[https://cognito-idp.us-east-1.amazonaws.com/us-east-1_e4iVm1J4X/.well-known/openid-configuration](https://cognito-idp.us-east-1.amazonaws.com/us-east-1_e4iVm1J4X/.well-known/openid-configuration)

This endpoint provides metadata about the OAuth2 authorization server, including the token_endpoint.

Discovered Token Endpoint Example

Upon querying the well-known configuration endpoint, you would discover the token endpoint. Then you post your client id and client secret to the token endpoint.

Request Details

• Method: POST
• Content-Type Header: application/x-www-form-urlencoded
• Request Body Parameters:
  • grant_type: Must be client_credentials.
  • client_id: Your unique Client ID.
  • client_secret: Your confidential Client Secret.
  • scope: (Optional but recommended) Defines the permissions you are requesting. For FHIR, common scopes include system/*.read for read access to all system resources and system/*.write for write access. Consult b.well documentation for specific scopes applicable to your integration.

Example Request (using cURL)

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

curl -X POST \
  https://fhir.icanbwell.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=system%2F*.read%20system%2F*.write"

Example Success Response

A successful response will return a JSON object containing your access token and its expiration details:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600, 
  "scope": "system/*.read system/*.write"
}

• access_token: The actual token you will use to authenticate your FHIR API requests.
• token_type: Indicates how the token should be used (typically Bearer).
• expires_in: The lifetime in seconds of the access token. After this time, you will need to request a new token.