1. Home
  2. User Perspective Guides
  3. Backend Service Developers

Backend Service Developers

This page provides a high-level, Backend Services developer–oriented overview of the HALO specification. It identifies the responsibilities, lifecycle decisions, and conformance expectations that matter when implementing autonomous access to a Point of Care (PoC) FHIR API. It is a directional guide; the linked HALO pages and underlying specifications remain authoritative for implementation requirements.

Why HALO Matters to Backend Services Developers

By conforming to HALO, Backend Services gain:

  • Autonomous system-to-system access – Access PoC-hosted FHIR APIs without a user-driven launch, interactive authorization step, or active clinical session at runtime.
  • Consistent authorization – Use the SMART Backend Services authorization pattern across participating PoC implementations.
  • Governed onboarding – Establish an initial relationship with a PoC before registration and runtime access occur.
  • Least-privilege access – Operate within pre-authorized and granted system/ scopes appropriate to the service's function.
  • Support for asynchronous workflows – Operate independently of an active user session to support approved system-to-system workflows.

Integration Pattern at a Glance

A HALO Backend Service is a confidential OAuth client that accesses a PoC-hosted FHIR API without a user-driven launch or runtime authorization interaction. The PoC pre-authorizes the service for an approved function, while the Backend Service authenticates with its own asymmetric credentials and requests only the system/ scopes needed for each operation.

The pattern separates one-time onboarding and trust establishment from recurring runtime access:

  • The PoC discovers the Backend Service through the App Catalog and invokes $initiate-onboarding to provide the initial context needed to begin onboarding.
  • The Backend Service and PoC complete the applicable registration and trust-establishment process before runtime access occurs.
  • The Backend Service uses the .well-known/smart-configuration to locate and validate the PoC authorization server's token endpoint and supported authentication capabilities.
  • At runtime, the Backend Service obtains a short-lived access token through the client credentials flow and uses it only for the authorized interactions supported by the PoC FHIR API.
  • When the PoC invokes $offboard, the Backend Service ceases requesting access tokens from, and accessing FHIR APIs at, that PoC.

Detailed registration, discovery, token acquisition, and FHIR API access requirements are defined in the Backend Services page and linked integration profiles.

Current Scope

This release covers a Backend Service accessing a PoC-hosted SMART-enabled FHIR server and authorization server. Registration and trust establishment are deployment-specific: $initiate-onboarding starts onboarding and discovery but does not prescribe Dynamic Client Registration or any other single registration mechanism.

Backend Services access through the SMART on FHIR Accelerator (SoFA) is not defined in this release. Backend Service discovery uses the App Catalog representation and onboarding endpoint defined by HALO; the subsequent registration and trust-establishment process remains deployment-specific.

Key HALO Sections for Backend Services Developers

  • Business Requirements – Review HALO's business, interoperability, and security requirements for Backend Services.
  • User Stories / Use Cases – Review the Backend Service related onboarding, read, and write use cases.
  • Overall Architecture – Understand the systems and trust boundaries involved.
  • App Catalog – Review the Backend Service catalog representation and lifecycle endpoints used for onboarding and offboarding.
  • Backend Services – Review the authorization model, registration constraints, runtime flow, scopes, and security guidance.
  • Operation: $initiate-onboarding – Review $initiate-onboarding parameters, responses, and error handling.
  • Operation: $offboard – Review $offboard parameters, responses, idempotency, and error handling.
  • Integration Profiles Overview – Entry point for navigating the HALO integration profiles relevant to your SoFA implementation. See Interoperability Recommendations for details on the specific profiles required for your implementation.
  • Design Considerations – Review responsible data access and modification guidance.
  • Privacy and Security Guidance – Review applicable privacy and security guidance.

Testing & Conformance Expectations

The following HALO use cases apply:

  • UC-05: Backend Service Discovery and Onboarding
  • UC-06: Backend Service Retrieves Patient Data from Point of Care Solution
  • UC-07: Backend Service Writes Patient Data to Point of Care Solution

Within these use cases, the Backend Service fulfills the CA:BS Onboarding Responder and CA:SoF Authorization Client roles. Read and write conformance can be claimed independently. See Interoperability Recommendations and Technical Use Case Sequence Diagrams for the applicable actor and transaction mappings.

In addition to HALO-specific requirements, Backend Service developers should ensure compliance with the following external specifications:

Responsibilities & Recommendations Checklist

Onboarding

  • Expose $initiate-onboarding at the endpoint communicated through the deployment's onboarding process.
  • Accept and validate the required iss and offboardingChallenge parameters before using them.
  • Store the offboardingChallenge securely alongside the resulting relationship so it can be used to validate a subsequent $offboard request.
  • Return a FHIR OperationOutcome describing the result or an actionable onboarding error.
  • Treat the operation as onboarding and discovery only, not registration, credential issuance, or authorization.
  • Be transparent to PoCs and jurisdictions about the data required and the operations the service intends to perform.

Offboarding

  • Expose $offboard at the offboardingEndpoint published in the App Catalog.
  • Match the required iss and offboardingVerifier to the backend service relationship being withdrawn.
  • Treat repeated requests as idempotent and return a FHIR OperationOutcome.
  • After accepting the request, cease requesting access tokens from and accessing FHIR APIs at the identified PoC.

Registration & Key Management

  • Complete the deployment-supported registration and trust-establishment process before requesting a token.
  • Retain the assigned client_id and register the hosted JWKS URL required for asymmetric client authentication.
  • Protect private keys and immediately rotate the affected key and notify the authorization server if a private key is compromised.

Discovery & Token Acquisition

  • Retrieve the PoC's SMART configuration, identify the token endpoint, and verify the required asymmetric client authentication capabilities.
  • Use the OAuth 2.0 client credentials grant with asymmetric client authentication over a protected connection.
  • Generate a new signed authentication JWT with a unique jti for every token request.
  • Request only the system/ scopes needed for the operation and within the service's pre-authorized permissions.
  • Request new access tokens as needed rather than caching tokens for extended periods.
  • Include a softwareStatement where required or supported by the deployment.

FHIR API Access & Operations

  • Send the bearer token only to the intended PoC FHIR resource server over a protected connection.
  • Perform only FHIR resource and interaction requests permitted by the granted scopes.
  • Do not send the PoC token when following a reference to another server; obtain separate authorization where required.

Security, Privacy & Audit

  • Apply jurisdictionally appropriate consent, purpose limitation, data minimization, retention, use, and disclosure requirements to data accessed or maintained by the service.
  • Produce and protect audit records for applicable access, modification, and disclosure events in accordance with HALO and jurisdictional requirements.