System Authentication

System authentication enables backend services and automated processes to access b.well APIs without a specific user context. Your service authenticates directly with b.well to obtain system-level access.

b.well uses OAuth 2.0 Client Credentials (RFC 6749) for secure server-to-server communication.

📘
How it Works

Service sends credentials — Your service sends Client ID and Client Secret to b.well's OAuth2 token endpoint

b.well validates credentials — b.well verifies your credentials and checks assigned permissions

b.well issues access token — b.well returns a system-scoped access token with assigned permissions

Access b.well APIs — Your service includes the access token in all requests to b.well APIs

Prerequisites

Complete these requirements during onboarding with b.well.

Configuration

b.well provides to you:

Item	Description	Example
Client ID	Your application's unique identifier for each environment	`your-client-id-sandbox`
Client Secret	Confidential secret key for authentication	`•••••••••••••••`
Base URLs	FHIR Server endpoint for your environment	Sandbox: `https://fhir.client-sandbox.icanbwell.com` Production: provided during onboarding

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

Scope Configuration

Your Client ID is assigned specific scopes during onboarding based on your integration requirements [1]. These scopes determine your data access permissions to b.well APIs.

Obtaining an Access Token

To access b.well APIs, your service authenticates using the OAuth2 Client Credentials flow. Send your Client ID and Client Secret to b.well's OAuth2 token endpoint to receive an access token.

The token endpoint is:

POST {base_url}/oauth2/token

Where {base_url} is your environment-specific FHIR Server endpoint (provided during onboarding).

Request parameters:

grant_type: Must be client_credentials
client_id: Your b.well Client ID
client_secret: Your b.well Client Secret
scope: Your assigned scope(s)

Response includes:

access_token: Use this to authenticate API requests
token_type: Always "Bearer"
expires_in: Token lifetime in seconds (typically 3600 = 1 hour)
scope: Granted permissions

Using the Access Token

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

Authorization: Bearer {your_access_token}

The token authenticates all requests to b.well APIs. Request a new token when the current one expires.

Implementation

Choose your integration path and follow its workflow guide for implementation details and code examples.

Integration Options:

b.well FHIR Server — Direct FHIR API access for backend services
FHIR SDK for Databricks — Simplified FHIR data access in Databricks notebooks

For FHIR Server-specific authentication setup with detailed examples, see FHIR Server Authentication Example.