Operation: $offboard

Overview

Within HALO, the PoC discovers the target system's App Catalog onboardingEndpoint from the App Catalog and invokes the $initiate-onboarding operation at that endpoint to request the backend services exposed by that system. The request carries the PoC's FHIR server base URL as the iss parameter, along with an offboardingChallenge derived from a verifier the PoC generates and retains locally. It also stores the supplied challenge alongside the resulting relationship so that a later Operation: $offboard invocation can be verified as originating from the same PoC (or one of its trusted subsystems) that completed onboarding. See Trust Considerations below for guidance on establishing trust between the PoC and the target system more generally.

To view the underlying FHIR OperationDefinition resource, see InitiateOnboarding.

URL: [base]/$initiate-onboarding

Trust Considerations

Implementers SHOULD establish an appropriate trust relationship between participating systems before onboarding or launch interactions occur, including mechanisms to verify that the party they are communicating with is an authorized member of the applicable trust community and is permitted to represent the stated issuer. HALO does not currently mandate a specific trust framework for establishing this assurance, and jurisdictions may define appropriate out-of-band trust arrangements based on their own governance and deployment models. Jurisdictions and implementers SHOULD consider UDAP where stronger, standardized trust assurance is required. The certificate-based trust, identity assertion, and registration mechanisms defined by UDAP can provide this assurance while operating as an additional layer on top of HALO; adopting UDAP does not require replacing or changing the HALO workflows and operations defined here. A future version of HALO may adopt a more prescriptive, UDAP-focused approach to trust establishment.

For more information, see UDAP – Unified Data Access Protocol and the FHIR Security for Scalable Registration, Authentication, and Authorization implementation guide.

Whether the system invoking $initiate-onboarding is itself authorized to act on behalf of the stated iss is likewise not established by this operation. As with app launch today, this relies on existing mechanisms such as whether the calling system is already registered and approved for use with that PoC's authorization server.

Expected Behavior

When a PoC chooses to enable and request the services of a target backend system, for example after an administrator has reviewed and approved the client within the App Catalog, the PoC invokes that system's $initiate-onboarding operation using an HTTP POST to the onboardingEndpoint advertised in the catalog entry. The request includes the PoC FHIR server base URL in the iss parameter, along with an offboardingChallenge derived from a verifier the PoC generates and retains for later use during Operation: $offboard.

Upon receiving the request, the target system acknowledges the invocation by returning an HTTP success response, evaluates the supplied context, and determines its next backend service steps. For example, it might use the iss value to fetch the PoC's SMART configuration from /.well-known/smart-configuration and use the discovered metadata, together with any service-specific policies, to decide how to proceed. Depending on the jurisdiction and implementation, those steps may include Dynamic Client Registration, another onboarding or trust-establishment process, discovery of token or FHIR endpoints for future runtime use, or a decision not to proceed. The target system SHALL store the supplied offboardingChallenge alongside the resulting relationship so it can later be used to validate an $offboard request for that PoC.

The PoC SHALL generate a fresh, cryptographically random verifier for each $initiate-onboarding invocation and SHALL NOT reuse a verifier across separate onboarding relationships. The PoC SHALL retain this verifier securely, since possession of it is what will later authorize the corresponding $offboard request. The target system SHALL likewise store the received offboardingChallenge securely and protect it from unauthorized disclosure or modification, since its integrity is what allows a subsequent $offboard request to be trusted.

The $initiate-onboarding operation itself does not grant API access or prescribe a single onboarding mechanism. Its role is to begin the onboarding process by providing the target system with the initial context needed to determine the appropriate next steps, if any, for enabling future backend service interactions.

Operation Failure

If the target system cannot process the invocation or validate the supplied request parameters, it SHALL return an OperationOutcome describing the issue so the PoC can surface an actionable onboarding error to the administrator.

Trust evaluation, metadata retrieval, and other subsequent onboarding activities may occur after the operation has completed. Any failures identified during those activities are outside the synchronous response to this operation and are handled according to jurisdictional and deployment-specific processes.

HTTP Response Codes

The $initiate-onboarding operation is a HALO-defined onboarding and discovery operation and does not map directly to a standard FHIR create, update, or transaction interaction. The following HTTP response codes are the expected baseline for implementers:

• 200 OK - The target system accepted the backend services request and returned an OperationOutcome confirming the result.
• 400 Bad Request - The request was malformed, including cases where the required iss parameter was missing or invalid.
• 405 Method Not Allowed - The caller used a method other than HTTP POST, or the server does not support this operation at the addressed endpoint.
• 422 Unprocessable Entity - The request was syntactically valid but could not be processed according to server rules, trust policy, or deployment-specific backend service requirements (for example, offboardingChallenge was invalid, or iss was not recognized).

Other standard HTTP status codes such as 401, 403, 404, and 500 may also be returned depending on deployment-specific security and operational behavior.

Examples

Invocation

See the initiate-onboarding-invocation-example example for more information.

Success Response

See the initiate-onboarding-success-response-example example for more information.

Error Response

See the initiate-onboarding-error-response-example example for more information.