Integration Policy

1. Purpose and Scope

This Integration Policy (the “Policy”) sets the standards, controls, and responsibilities that govern how AgroHub designs, builds, approves, operates, and retires integrations between the AgroHub platform and any internal or external system. It exists because AgroHub’s trade, financing, and verification workflows increasingly depend on real-time, automated connections to partners — and because several of those connections act as conditional gates on AgroHub’s own operational flow.

The Policy applies to every connection that moves data into or out of an AgroHub-managed system, in either direction, across four integration domains governed under a single framework:

• Partner trade-technology integrations — logistics and trade-facilitation services that AgroHub consumes as conditional gates (e.g. galaxeFi BookIn and E2E Visibility).

• Data and verification integrations — satellite and agronomy intelligence feeding AgroHub’s due-diligence engine (e.g. Farmdar satellite imagery; BaKhabar Kissan field and weather data).

• Financier and payment integrations — connections to financiers, Takaful operators, and payment rails supporting Shariah-structured settlement.

• Internal and inbound API integrations — AgroHub’s own services, and third parties consuming the AgroHub Data Intelligence API.

It binds all AgroHub employees, contractors, and any partner who requests, builds, reviews, approves, or operates an integration with AgroHub. It pairs with the AgroHub Service Level Agreement, which defines the availability and support commitments for AgroHub’s production services.

2. Definitions

3. Guiding Principles

• Real-time and event-driven. Status changes propagate automatically through APIs and webhooks, without manual re-keying.

• Conditionally gated. Where a transition is gated, it stays blocked until the partner returns a successful, authenticated response.

• Resilient by design. Because gated partners become critical-path infrastructure, integrations must degrade gracefully and never strand a transaction.

• Auditable. Every gated decision and milestone is logged for AgroHub, the partner, and financiers.

• Secure by default. Least privilege, encryption in transit and at rest, and explicit authorisation on every connection.

• Shariah-aligned data handling. Data used to evidence Salam, Murabaha, Wakala, or Takaful structures is sourced, retained, and disclosed consistently with the relevant contract and advisory guidance.

• Owned, documented, reversible. Every integration has a named owner, a Register entry, and a documented rollback and decommissioning path.

4. Integration Domains and Approved Patterns

AgroHub standardises on a small set of patterns. Teams select the highest-ranked pattern that meets the requirement; lower-ranked patterns require an exception (Section 13).

4.1 Partner Trade-Technology Integrations

Trade-tech partners such as galaxeFi are consumed over authenticated APIs and webhooks. Designated services act as conditional gates on AgroHub’s fulfilment flow (Section 5). Each AgroHub lot or order is mapped to the partner’s booking reference by a Correlation ID, and every request carries an idempotency key so retries and duplicate event deliveries are safe.

4.2 Data and Verification Integrations

Satellite and agronomy partners — Farmdar for imagery-derived crop intelligence, and BaKhabar Kissan for field monitoring, advisory, and weather-station data — feed AgroHub’s due-diligence engine. These integrations are read-heavy; AgroHub records the data’s provenance, refresh cadence, and the confidence it carries into financing and verification decisions.

4.3 Financier and Payment Integrations

Integrations with financiers, Takaful operators, and payment providers require a completed security review, a signed data-protection agreement, and a documented data flow. A conditional gate that confirms an operational fact (e.g. goods delivered) does not transfer credit, repayment, or settlement risk to a technology partner; risk allocation is governed by the relevant commercial agreement.

4.4 Internal and Inbound API Integrations

Internal AgroHub services route through the platform’s API layer and authenticate with managed service accounts. Third parties consuming the AgroHub Data Intelligence API must register an application, use scoped credentials, and comply with the published API terms, rate limits, and versioning policy. AgroHub supports the current major API version plus one prior version, with a minimum 180-day deprecation notice.

5. Conditional Gates

Conditional gates are the core of AgroHub’s partner integrations. The following AgroHub transitions remain blocked until the corresponding partner response is received and authenticated. The catalogue is maintained in the Integration Register and per-partner annexes.

Note: A conditional gate confirms an operational fact; it does not move credit, repayment, or settlement risk to a technology partner. Every gate must have a defined fallback so a partner disruption never strands a transaction (Section 10).

6. Integration Lifecycle

Every integration moves through six governed stages, each with required artifacts and an accountable role.

7. Roles and Responsibilities

8. Authentication and Security

• Authentication. OAuth 2.0 or mutual TLS for service-to-service; scoped API keys only where a partner does not support stronger methods.

• Authorisation. Least-privilege scopes; no shared or human credentials in automated integrations.

• Signed webhooks. Inbound event payloads are signed and origin-verified before they can release a gate.

• Secrets. All credentials held in the approved secrets manager — never in code, config, or tickets — and rotated at least every 90 days.

• Encryption. TLS 1.2+ in transit; encryption at rest for stored payloads and logs.

• Environment separation. Distinct sandbox/UAT and production credentials and endpoints; production data is never copied unmasked into lower environments.

• Idempotency & correlation. Every request and event carries an idempotency key and a Correlation ID for safe retries and end-to-end traceability.

9. Data Governance and Privacy

Integrations move the minimum data necessary for the stated purpose. Personal or sensitive data — including farmer identity, landholding, and financial data — requires Data Owner and compliance approval, a documented lawful basis, and a recorded retention period. Each partner integration is covered by a data-protection agreement defining what flows each way, ownership, and retention. Cross-border transfers use an approved transfer mechanism. Provenance and confidence of satellite and agronomy data are recorded so AgroHub can evidence the basis of any financing or verification decision.

10. Reliability, Resilience, and Failure Handling

Because gated partners are critical-path, AgroHub designs every gate to fail safe:

• Retries with back-off. Transient failures retry with bounded exponential back-off; undelivered events go to a dead-letter queue.

• Reconciliation. Scheduled jobs periodically re-sync booking and milestone state to catch missed or duplicated events.

• Manual override. A defined exception path with dual authorisation and full audit trail can release a gate during a confirmed partner outage.

• Graceful degradation. Documented rules specify which steps may proceed provisionally and which must hard-block while a partner is unavailable.

• Monitoring. Each production integration emits health, latency, and error-rate metrics with alert thresholds and a runbook.

11. Change Management and Versioning

Changes to production integrations follow the standard change process: peer review, sandbox testing, an approved change record, and a rollback plan. AgroHub’s published APIs follow semantic versioning; breaking changes ship under a new major version with at least 180 days’ notice. New or changed gated services with a partner go through a joint change-control process and an updated integration annex.

12. Integration Register

AgroHub maintains a central Integration Register as the system of record. No integration runs in production without a current entry. Each entry records, at minimum:

• Name, owner, partner, business purpose, and lifecycle stage.

• Source and destination systems, direction, pattern, and any conditional gate it controls.

• Data classification, sensitive-data flag, provenance, and retention period.

• Authentication method, credential location, and SLA tier.

• Fallback / degradation rule, monitoring location, and runbook link.

• Partner agreement, annex, and certification references.

The Register is reviewed quarterly; entries unverified for more than twelve months are flagged for recertification or decommissioning.

13. Exceptions

Any deviation from this Policy requires a documented exception approved by Security and the CTO. Exceptions state the business justification, compensating controls, residual risk, and an expiry date not exceeding twelve months. Expired exceptions must be renewed or remediated. Bypassing a conditional gate outside the Section 10 manual-override path is never permitted.

14. Compliance and Enforcement

Adherence is mandatory. Non-compliant integrations may be suspended or disconnected without notice where they present a security, privacy, financial-integrity, or availability risk. Compliance is assessed through periodic audits of the Integration Register and production environments. Repeated or willful non-compliance is handled through AgroHub’s disciplinary and partner-management processes.

15. Review and Revision History

This Policy is reviewed at least annually by the document owner and updated as the platform, partners, regulations, and risks evolve.