FHIR Server Authentication

This guide provides detailed examples for authenticating with b.well's FHIR Server using OAuth 2.0 Client Credentials. Use these examples to set up system-level authentication for direct FHIR API access.

Prerequisites

Before you begin, ensure you have:

⚠️ Security

Treat your Client Secret like a password. Never expose it in client-side code, version control, or public repositories.

Discovering the Token Endpoint

The OAuth 2.0 token endpoint can be discovered via the OpenID Connect well-known configuration endpoint:

Well-Known Configuration Endpoint:

• Client-Sandbox:https://fhir.client-sandbox.icanbwell.com/.well-known/smart-configuration

Important: Always discover the token endpoint from the well-known configuration - do not hardcode it. The endpoint URL may change. You can cache the configuration response for up to 24 hours.

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

Once you've discovered the token endpoint, you can proceed to obtain an access token by posting your Client ID and Client Secret to that endpoint.

Obtaining an Access Token

Send a POST request to the token endpoint with your Client ID and Client Secret to receive an access token.

Token Endpoint:

POST https://fhir.client-sandbox.icanbwell.com/oauth2/token

Request Headers:

Content-Type: application/x-www-form-urlencoded

Request Body Parameters:

• grant_type: Must be client_credentials
• client_id: Your b.well Client ID
• client_secret: Your b.well Client Secret

Example Request (cURL)

Replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual credentials.

curl -X POST \
  https://fhir.client-sandbox.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 returns a JSON object containing your access token and expiration details:

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

Response fields:

• access_token: The token you'll use to authenticate your FHIR API requests
• token_type: Indicates how the token should be used (typically Bearer)
• expires_in: Token lifetime in seconds (after this time, request a new token)
• scope: The permissions granted to this access token

Using the Access Token with FHIR Server

Include the access token in the Authorization header of your FHIR API requests:

Request Format:

GET /4_0_0/Patient?name=John HTTP/1.1
Host: fhir.icanbwell.com
Accept: application/fhir+json
Authorization: Bearer {YOUR_ACCESS_TOKEN}

Replace {YOUR_ACCESS_TOKEN} with the actual OAuth2 token you obtained. The specific FHIR endpoint, version (e.g., /4_0_0/), and resource (e.g., Patient) will depend on the data you wish to access.

Example with cURL:

curl -X GET \
  https://fhir.client-sandbox.icanbwell.com/4_0_0/Patient?name=John \
  -H "Accept: application/fhir+json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Additional Resources

• System Authentication - Overview of OAuth 2.0 Client Credentials flow
• b.well FHIR Server Overview - Complete FHIR Server integration guide
• FHIR Server GitHub Repository - Technical documentation and specifications
• FHIR Server Cheatsheet - Quick reference for common operations