CHAPTER 09
Integration and Application Development
Adopt individual capabilities, connect existing applications, and build branded experiences through defined interfaces.
- Application
- API contract
- Identity
- Wallets
- Data
Organizations rarely replace their entire technology estate to adopt one new capability. Hybrid-Chain's integration model is designed around selective adoption: an existing application can connect to a relevant module, and a broader platform can compose several modules into a branded experience.
Contracts as the integration boundary
The public API reference organizes capabilities into modules and operations. For a working integration, the target deployment's current contract defines the request, response, authorization, and error behavior. Product descriptions explain purpose; machine-readable contracts and operation documentation establish the interface an engineer can actually use.
An operation's presence in a catalog should be read together with its status. A planned capability describes intended scope, while a published executable contract describes an implemented interface. Even an implemented interface can depend on permissions, resource state, configuration, or downstream availability. This distinction lets teams plan without mistaking a roadmap entry for an enabled service.
From request to confirmed outcome
Reliable integration requires understanding what a response means. Acceptance may indicate that work has been received, not that it has finished. Event delivery may inform an application that something changed, while a subsequent authorized read establishes the current state. Retries should follow the documented operation semantics and reconcile uncertain results before creating a new consequential request.
Automation and notification capabilities help connect platform events to external applications. The receiving application remains responsible for verifying the relevant message and authorizing its own side effects. A delivery acknowledgment and a completed business process are separate outcomes, and operational interfaces should make both understandable.
Choosing an integration surface
| Approach | Best suited to | Engineering responsibility |
|---|---|---|
| REST / documented request-response API | Explicit reads, proposals, and individually authorized operations. | Validate the exact contract, permissions, idempotency behavior, and meaning of acceptance. |
| Events and real-time updates | Keeping a UI or downstream workflow informed when relevant state changes. | Use the supported transport; establish authentication, ordering, replay, deduplication, and a canonical read for reconciliation. |
| White-label or embedded application | A branded journey that combines several product capabilities. | Preserve custody, permission, privacy, and availability boundaries behind the presentation. |
These approaches are complementary. An embedded merchant interface may issue a documented request, receive a supported update, and then read authoritative state before showing completion. WebSockets are one real-time interaction pattern; they should not be assumed to be available for every module. Select the transport and delivery guarantees actually documented for the target deployment.
Branded and embedded experiences
White-label and partner applications can present a business-specific journey while drawing on the platform's capabilities. The value is the ability to focus the user experience on a particular market or operating process without independently assembling every underlying module. Branding does not change the actual authority, custody, or availability boundaries of the chosen services.
An integration can start with an authorized read, evidence inspection, or policy evaluation before adding an enabled action. This provides a practical progression: establish the meaning of the data, agree responsibilities, test expected and denied cases, and then evaluate the complete workflow under its intended conditions.
FROM ARCHITECTURE TO INTERFACE
Engineering references
Start with capability discovery, inspect the exact contract, and follow the resources published for the chosen environment.
Discover the capability registry
Relate a business capability to the platform's operation catalog.
GET/api/v2/capabilities- Observable result
- The V2 capability registry and its documented status information.
- Authority and limits
- A planned entry is not an executable contract or an enabled deployment.
Read the machine-readable contract
Use the target deployment's specification to implement the selected interface.
GET/api/v2/openapi.json- Observable result
- The published OpenAPI description of operations, schemas, responses, and security requirements.
- Authority and limits
- Contract presence does not bypass authentication, resource authority, or runtime readiness.
Discover integration resources
Find the platform's public integration entry points.
GET/api/v2/developer-portal- Observable result
- SDK, environment, authentication, reference, and guide discovery metadata.
- Authority and limits
- Use the resources and environment actually returned; discovery is not credential provisioning.
Selected operations were checked against the public OpenAPI contract on October 1, 2026. Links open documentation; they do not invoke an operation. Authentication, exact schemas, and deployment requirements remain defined by the current contract.
OPERATING THROUGH INTERRUPTIONS
Keep an interrupted workflow explainable.
The integration's recovery behavior is part of its design, not an afterthought. The situations below describe how a client should preserve authority and reconcile uncertainty; they do not promise universal rollback, exactly-once execution, or a particular service-level objective. Match each response to the exact operation and error returned by the target deployment.
Access is revoked or authentication expires
Stop the dependent action and surface the denied or expired state. For approved-context reads, current publication, audience, scope, and binding checks matter. Do not bypass a denial with an older credential or cached context treated as current authorization. Restoring access requires the responsible owner's approved process.
- Retain for review
- Operation, resource reference, effective request identifier, error code, and the responsible access owner—never the credential.
- Acceptance check
- A 401 or 403 is not converted into a generic retry-until-success loop.
A policy or budget changes during review
An AI Wallet dry run is a point-in-context evaluation and reserves no budget. When relevant state changes, obtain a fresh evaluation of the exact terms before relying on it. A response indicating that no active policy is available is a condition to resolve, not an invitation to execute without policy.
- Retain for review
- The original and refreshed policy references, evaluation inputs, returned reasons, and the business review decision.
- Acceptance check
- Old approval, policy, or budget observations are not silently presented as current.
The response times out
Distinguish a retryable read from a mutation whose outcome is unknown. Inspect authoritative state using an available read before deciding whether another mutation is safe. If the operation requires Idempotency-Key, reuse it only for a byte-equivalent retry of that logical request. Do not introduce a new key merely because the first response was lost. Signed-request freshness and nonce rules still apply independently.
- Retain for review
- A private request ledger with logical operation identity, exact submitted payload reference, available correlation IDs, and the last observed state.
- Acceptance check
- When no authoritative read can resolve the outcome, keep it unresolved and escalate instead of risking a duplicate financial action.
An upstream service is unavailable
Treat a 503 as unavailable evidence or unavailable execution authority, not as an empty successful result. Use bounded retry and backoff appropriate to the contract, honor retry guidance when supplied, and give the user a clear pending explanation. A fresh signed workload request needs fresh valid signing headers; a nonce must not be reused for another request.
- Retain for review
- The unavailable dependency, last successful observation time, retry budget, and escalation owner.
- Acceptance check
- A stale observation is visibly dated and cannot substitute for the authorization needed by a later action.
Only part of the business journey completes
If context review succeeds but payment has not been authorized, preserve those as separate states. If a financial operation has been broadcast, cancellation or reversal cannot be inferred from an application error. Use only the supported cancellation, reconciliation, or recovery process for that specific stage and network; compensating business action requires its own authorization.
- Retain for review
- Completed and pending stages with their actual references, plus any authorized compensation decision.
- Acceptance check
- The interface never labels the whole workflow failed or complete solely from one stage's HTTP response.
Normal key or data access is lost
Route recovery to the owners named in the deployment's custody and data-handling plan. Test wallet recovery and protected-data retrieval separately in an agreed environment. A visible object, shard count, wallet enrollment, or public readiness record is not a substitute for a demonstrated recovery exercise.
- Retain for review
- Responsible participants, approved procedure, tested scope, observed recovery outcome, and unresolved dependencies.
- Acceptance check
- Untested recovery remains explicitly untested, and secrets are never copied into a support ticket or public evidence record.
A robust client reports three things distinctly: what it requested, what the authoritative service says, and what the business can safely do next. Preserving that distinction makes support, audit, and recovery more effective.
ADOPT IN CONTROLLED STAGES
Start with one useful outcome. Expand the proven connection.
An organization can retain its existing application and adopt one Hybrid-Chain capability around a specific problem. Each phase below has an exit condition. Advancing depends on observed behavior and agreed authority—not simply enabling another product in a diagram.
- Inspect
- Connect context
- Evaluate
- Authorize separately
- Operate
Begin with a read-only evaluation
Choose one question, such as identifying the version of a protected record used in a review. Select the intended environment, inspect the live contract, arrange limited credentials, and implement the permitted metadata read in the existing application.
- Retain for review
- A small evaluation report containing the question, owner, contract, resource references, and redacted observations.
- Acceptance check
- The application shows the right record, denies the wrong scope, and explains missing or unavailable data.
Connect approved context to the existing workflow
Add a reviewed collection where an assistant or partner needs relevant knowledge. Agree who prepares and approves that context. Preserve supported relationships between the source review and the collection without copying confidential source content into public records.
- Retain for review
- A publication and audience decision, workload binding, source relationship, and revocation test.
- Acceptance check
- The intended recipient can read the approved context; an unintended participant cannot.
Add policy evaluation before any financial action
Use AI Wallet Control's dry run to evaluate precisely typed proposals. Keep the current business review process in place. Exercise accepted, denied, stale-policy, invalid-input, and unavailable-service cases without attempting funds movement.
- Retain for review
- Evaluation inputs, policy references, returned reasons, and the reviewer's acceptance criteria.
- Acceptance check
- The user understands that a preview decision is not a reservation, approval, or executed payment.
Introduce a separately enabled execution route
Only after agreeing custody, credentials, approvals, network, asset, destination controls, and operating responsibilities should the team evaluate the chosen financial route. Use the appropriate test environment and contract-specific authorization, signing, idempotency, and reconciliation procedures.
- Retain for review
- An agreed route-specific test plan and evidence for each supported stage, including denied and interrupted cases.
- Acceptance check
- The team can reconcile an ambiguous outcome and demonstrate that no action exceeds its authorized terms.
Expand once operations are repeatable
Add further sources, agents, or product capabilities after the initial connection has clear monitoring, support ownership, privacy controls, and recovery practice. Revisit authority when audiences or workloads change rather than copying a broad permission set to every new participant.
- Retain for review
- An operating runbook, acceptance review, escalation contacts, and a change-control record for the expanded scope.
- Acceptance check
- The next integration reuses proven practices while still validating its own contract and authority boundary.
This sequence keeps adoption tied to business value: first answer a useful question, then improve a decision, then evaluate a controlled action. The platform grows around the application rather than requiring a wholesale replacement before it can contribute.
Developer value
The platform's modular structure reduces the need to invent a separate conceptual model for each connected task. Identity, resource context, authority, and evidence recur across products. Engineers still implement the exact contracts they use, but they can reason about them within a shared architecture. That consistency is especially valuable when the same capability must serve a customer interface, an internal application, and an automated agent.
Integrating Hybrid-ID without merging authority boundaries
For a participating business application, begin with the Hybrid-ID developer and SSO guides. The supported web flow uses an operator-registered application, exact HTTPS callback URLs, approved scopes, and Authorization Code with PKCE S256. Redirect the person to Hybrid-ID instead of collecting their Hybrid password. Use the canonical issuer's discovery metadata and a maintained OIDC client to validate the response and establish your own application session.
Use issuer and subject to recognize the returning identity. Request only the claims needed by the registered integration, and distinguish consent to identity disclosure from membership in an organization or permission to use a product. The provider's pairwise subjects should not be replaced with email-based assumptions about account equivalence across unrelated applications. Keep client credentials and code exchange in the trusted server integration described by the guide.
The OIDC provider's discovery and protocol endpoints are separate from Hybrid-Chain's V2 product API catalog. Approved first-party account APIs and inbound federation routes have different purposes from outward-facing Hybrid-ID SSO. After sign-in, confirm the authority required by each product operation; an OIDC session is not a universal wallet, vault, or workload credential. Unified agent access and self-service client registration should not be inferred from the existence of a developer page.
A useful integration exercise checks a returning user's own workspace, a user without the required organizational membership, and an unavailable or withdrawn product permission. The application should explain each result without leaking another organization's data or silently giving an agent additional powers. This tests the connection between identity and business access while preserving each service's independent responsibility.