External Integration Contracts and SDKs

Overview#

A partner organisation building a custom connector to the platform needs to know which API fields are stable, which are scheduled for retirement, and which TypeScript types to import. Without a governed integration surface, every platform update risks breaking their integration with no warning. External Integration Contracts and SDKs solve this by publishing versioned contracts, compatibility rules, and supported client libraries so external teams can build reliable integrations without reverse-engineering private implementation details.

This module is for organisations that need long-lived partner integrations, connector ecosystems, or customer-managed extensions backed by a stable, auditable contract. It reflects the platform's commitment to rule 10a: any change to a third-party-facing surface must update the external contract artifacts and affected SDKs in the same change.

Key Features#

• Versioned External Contracts: Publish stable contract versions with clear compatibility expectations for external integrations. Each version covers the curated GraphQL operations, REST/OpenAPI routes, auth scopes, token claims, and connector manifest fields that partners may depend on.
• Compatibility and Deprecation Guidance: Track what is current, what remains supported, and what is scheduled for retirement so partners can plan safely. The deprecation matrix records timelines and migration paths.
• Client SDK Support: Maintained TypeScript and Python client libraries for common integration scenarios, covering both server-side and client-side integration patterns. Partners do not need to build from scratch.
• Example-Driven Onboarding: Quickstarts and reference patterns reduce the time from contract review to working integration. Examples cover the most common investigative platform integration scenarios.
• Connector Alignment: External client contracts stay aligned with the broader connector and extension model used across the platform, including connector manifest fields and realtime payload structures.
• Operational Trust: API shape, change timing, and migration expectations are explicit rather than implied. Partner integrations break less because changes are coordinated and communicated in advance.
• Partner-Ready Documentation: The integration surface is described in terms external teams understand without exposing internal implementation details or proprietary analytical methods.

Use Cases#

• Partner Platform Integration: Give trusted partners a stable contract for operational data exchange and workflow integration against a surface that is versioned and governed.
• Customer-Built Extensions: Support customer development teams building their own connectors and automation against a supported public surface, with TypeScript and Python SDKs accelerating their work.
• SDK-Based Acceleration: Reduce integration effort for common client stacks by providing maintained language bindings and executable examples.
• Managed Deprecation: Move external integrations forward safely with clear migration planning rather than disruptive change. Partners receive advance notice and migration guidance before breaking changes ship.

Integration#

• Connector registry and external integration services
• Versioned contract publication and compatibility governance
• Partner onboarding and developer enablement workflows
• Public API and extension management services
• Audit trail for all contract-version-affecting changes per platform governance rules

Open Standards#

• OpenAPI 3.1 (RFC 8615 well-known): The versioned external contract is published as a curated OpenAPI 3.1 descriptor at /.well-known/openapi.json and /.well-known/openapi.yaml, following the RFC 8615 well-known URI convention so standards-aware tooling (Postman, Insomnia, Redocly CLI, openapi-generator-cli) can locate the descriptor without bespoke configuration.
• GraphQL (June 2018 specification): Approved partner operations are delivered as curated GraphQL bundles over a typed transport with bearer authentication and tenant scoping, rather than exposing full schema introspection or raw playground access to external integrators.
• OAuth 2.0 / RFC 6749 and RFC 7523: Service tokens and integration credentials are issued via the OAuth 2.0 authorization code and client credentials flows; machine-to-machine automation uses service tokens backed by RFC 7523 JWT assertions.
• RFC 7517 / RFC 7519 (JWKS and JWT): Tokens are signed with RS256 or ES256 keys published at the OpenID-compatible /.well-known/jwks.json endpoint so partners can verify Knogin-issued JWTs against public key material without accessing private signing details.
• RFC 9727 (API catalog link-set): The /.well-known/api-catalog endpoint returns an RFC 9727 link-set that advertises every machine-readable artefact, OpenAPI JSON, OpenAPI YAML, provenance verify keys, from a single anchor, giving partner tooling a standards-based bootstrap without bespoke discovery logic.
• RFC 8594 (Sunset and Deprecation headers): Every route listed in the deprecation matrix automatically emits RFC 8594 Sunset and Deprecation headers with IMF-fixdate timestamps and a Link: rel="successor-version" pointer, allowing partners to wire a single header check into their HTTP client and surface migration notices long before a breaking change ships.
• W3C Trace Context (traceparent / tracestate): All API responses carry X-Argus-Trace-ID and X-Argus-Span-ID; partners may submit traceparent on requests to anchor Argus spans within their own observability backend, following the W3C Trace Context specification.
• OWASP ASVS 5.0: The external integration surface is designed and reviewed against the OWASP Application Security Verification Standard 5.0 (L2 baseline for public endpoints, L3 for auth and token-issuance surfaces), covering input validation, token lifetime, PKCE enforcement, credential rotation, and rate-limiting hard caps.

Last Reviewed: 2026-03-25 Last Updated: 2026-04-14