Documentation

Appearance

Connect the Product API and integrations #

Use the Product API when a customer's business system needs instance-scoped access to Product Records or exposed Operations. Use integrations when a Product Application must call out or accept a bounded inbound event or Operation.

These are customer product interfaces. Application authoring, publishing, and rollout remain OEM organisation workflows.

Scope every client to one Product Instance #

Create API clients under Access and grant only the required record or Operation permissions. A client secret authenticates to one Product Instance; it must not become a cross-customer master key.

Treat the plaintext secret as a credential:

  • store it in a secrets manager
  • never embed it in customer-facing JavaScript or device images
  • rotate or revoke it when ownership changes
  • give separate systems separate clients
  • test that a client cannot access another instance

Follow the generated contract for the instance rather than copying an internal route from the browser. Route shapes and implementation details are not the stable product design.

Work with Product Records #

Within the client's permissions, the Product API can list, create, read, update, and archive Product Records for an exposed model. Record validation, schema, permissions, secret-field handling, and customer isolation are the same domain rules used by the portal.

Use idempotency keys for writes and Operation invocations where supported. Idempotency prevents one repeated request from becoming another cloud-side intent. It does not make downstream physical or commercial side effects exactly once.

Query records predictably #

Product Query supports bounded:

  • typed field filters
  • ascending or descending ordering
  • field selection
  • cursor pagination
  • optional total count
  • optional archived-record inclusion when permitted

Operators depend on field type. For example, record references support equality, membership, and null checks rather than arbitrary text or range operators. Query only published field keys and handle validation errors as contract errors.

Use the returned cursor for the next page. Do not construct or edit cursor values, and do not assume offset pagination.

Build bounded reporting #

Reporting aggregates can calculate count, sum, average, minimum, and maximum over permitted records. They also support bounded grouping or datetime time buckets with deliberately constrained combinations.

CSV export streams a bounded result and includes query and schema metadata. Use it for operational extracts, not as an unlimited warehouse export.

For joins, arbitrary full-text search, long-term analytics, or high-cardinality reporting, copy authorised data into a customer-owned reporting system through a designed integration.

Invoke customer Operations #

Expose only Operations intended for API use. Define typed input, permissions, idempotency, and an outcome the calling system can reconcile.

An Operation may start a Process or invoke a Command, but its accepted response does not prove that a physical action completed. Follow the returned invocation state and the product's reported truth.

Send outbound integrations #

An outbound integration binding lets a Rule, Operation, or Process call an approved integration. The generic HTTPS integration:

  • requires a public HTTPS destination
  • rejects embedded URL credentials and private or non-public destinations
  • supports bounded methods, timeout, response size, and retry attempts
  • can apply a separately managed bearer, basic, or header credential
  • records invocation and delivery state
  • carries idempotency and correlation identity

Synchronous success means the remote endpoint returned an accepted HTTP response. It does not prove the remote business process finished. For queued or asynchronous delivery, design duplicate handling and terminal reconciliation.

Durable outbound deliveries retry retryable failures with bounded attempts. After retries are exhausted, the delivery enters a dead-letter state. A deliberate operator replay starts a new attempt cycle and records Product Activity; it does not erase the earlier attempts or make the remote side effect exactly once.

Accept inbound integrations #

An inbound endpoint belongs to one Product Instance and has an allowlist of event and Operation keys. Requests require the endpoint secret, an idempotency key, and may include an HMAC signature and correlation identifier.

Inbound handling:

  • authenticates the instance endpoint
  • enforces its action allowlist and rate limit
  • verifies a supplied signature
  • deduplicates by idempotency key
  • ingests the event or invokes the Operation
  • records receipt and Product Activity

Do not expose a general authoring or arbitrary Process-step endpoint. Inbound systems can perform only the actions explicitly allowed for that endpoint.

Test integrations safely #

Use an application sandbox and deterministic Scenario responses before using real endpoints. Then test:

  • duplicate delivery
  • timeout and non-success HTTP status
  • malformed or oversized response
  • revoked or rotated credentials
  • invalid signature and rate limiting
  • external success followed by local failure
  • local success followed by uncertain external state

Do not place real payment or production credentials in fixtures. A sandbox Scenario proves application orchestration, not a third party's production behaviour.