Connect systems with API keys, webhooks and EPCIS

API keys

An API key is for machine-to-machine access. The secret is shown once and stored as a hash, with a visible prefix for identification and a last-used timestamp so you can tell an active integration from a forgotten one. Keys expire and can be revoked.

Scopes decide what a key may do - read or write against a resource - and a key acts as the member who created it for attribution purposes without inheriting that member's role. If the owner of a key is gone, the key cannot act: an audit trail that names nobody is not an audit trail.

Outbound webhooks

A webhook subscribes your endpoint to a set of events. Every delivery is signed, retried with backoff on failure, and recorded in a delivery log with the status code and error, so you can tell a partner that their endpoint returned an error rather than guessing.

A stored delivery can be replayed, which is what you need after fixing an endpoint. Deleting a webhook also removes its delivery history, so export anything you need to keep first.

EPCIS 2.0

An EPCIS subscription is a standing query over the lifecycle event stream: which event types, business steps, dispositions, product identifiers, categories or passports you want, and where to send them. Matching events are pushed as standard object events.

A subscription is implemented as a webhook with a filter, which means it inherits signing, retries, delivery logging and replay for free - and it also means the filter is never bypassed. Use the test action to prove an endpoint before you rely on it, and the bounded backfill to catch a new subscriber up on history.

Data quality of the stream

Lifecycle events come from your own records and from partner captures you import. An import is idempotent per event identifier, so a partner that retries a batch does not create duplicates, and system-owned events such as commissioning are refused because the platform already records them.

The delivery body is a platform envelope; the standard object event sits inside it. Recipients should read the payload rather than assuming a bare event.

Before you go live

Give each integration its own key, so revoking one does not break another. Point webhooks at a staging endpoint first and check the delivery log, because a signature mismatch is much easier to debug there than in production. And keep the key out of source control - the console shows it exactly once.

Integration hub: mappings and feeds

Use the integration hub to keep passports in step with an ERP, PIM or PLM export. A mapping says which source field holds the SKU or GTIN and which source field fills which target: a product identity field (product.brand) or a passport data path (data.materials.0.recycled_percent). Each rule has a transform - number with decimal comma and unit scale, integer, yes/no, date, country code, upper or lower case - and an optional value map such as Li-ion=lithium-ion. Empty source values never blank a target.

Upload a CSV or JSON file and preview the per-record diff first; applying writes only values that differ, as a new schema-validated passport version, and a re-run with the same data changes nothing. Owners and administrators can attach an https feed with an optional bearer token (stored encrypted, never shown again, and cleared if the feed moves to another host) and apply it daily. Every run is recorded, and a passport field's provenance names the mapping and run that wrote it.

Templates, XML, SFTP, OAuth and push

Start a mapping from a template for SAP S/4HANA (Product API or MATMAS IDoc), SAP Business One, Dynamics 365 Business Central, NetSuite (SuiteQL), Odoo, Akeneo, Pimcore, Salsify, Plytix or a PLM bill of materials; each lists what to check against your own export. Sources can be CSV, JSON or XML (namespaces and repeated segments handled; documents with a DOCTYPE are refused).

Feeds can be fetched over HTTPS - GET or POST with a body for GraphQL, OData or SuiteQL - with a bearer token, basic credentials, a key in a named header, or OAuth 2.0 (a token is requested for each run), or read over SFTP with a password or private key against a pinned host key (Test feed shows the key the server presents). They can run hourly or daily. Instead of a feed, your system can push records to the mapping with its push token. A mapping can also create the products and passports that match no existing product.

Bills of materials from PLM

A BOM mapping reads one component line per record - parent part, component part, quantity, mass, find number - and keeps each parent's structure in step: lines are added, updated or removed, a component whose part has a passport is linked to it, and a link that would make a product its own component is refused. A run only touches the lines that mapping created; components entered by hand stay.

Asset Administration Shell (AAS) export

Every passport can be exported as an Asset Administration Shell in the AAS metamodel V3 JSON format, for digital twin registries, AAS servers and industrial data exchanges: choose AAS export on the passport, or call GET /dpp/{id}/aas.json (the published version by default, or ?version=). A published passport also offers GET /public/dpp/{id}/aas.json with exactly what its public page shows.

The shell carries a Nameplate submodel under the Digital Nameplate semantic ID, a DigitalProductPassport submodel with every data field as typed properties, collections and lists, and a Components submodel referencing each component passport's own shell. Submodels other than the Nameplate use platform semantic IDs; they follow the metamodel without claiming conformance to a specific IDTA template.

Screen-by-screen reference

These pages were checked in the organization console on 8 October 2026 using an isolated sample organization. Controls can differ by role, plan, record state and configured providers. Each page below explains its purpose, a practical workflow, the visible controls and what to verify afterward.

API keys (/settings/api-keys)

API keys give integrations scoped access to organization endpoints and can expire independently of a browser session.

Name a key for one integration and choose the smallest scope set that supports its specific endpoints. Copy the secret at creation into the intended secure system because the raw value is not displayed later. Use status and last-used information to retire unused credentials; a key cannot exceed its creator's current access.

The full secret is not retrievable after creation.

Controls and options

• Give the key a name and optional expiry in days.
• Select only the scopes the integration needs, then Create key and copy the secret once.
• Inspect the key list for status and last use; revoke an unused or exposed key.
• A member-created key is limited by that member's current role and workspace access.

Webhooks (/settings/webhooks)

Event subscriptions send signed organization events to your HTTPS endpoint and keep delivery attempts for troubleshooting.

Subscribe an HTTPS receiver to only the event types it needs and store the signing secret in that receiver. After adding the endpoint, inspect delivery attempts and response codes to see whether it accepted events. Replaying a failed attempt may deliver a duplicate, so the receiver should deduplicate and verify signatures before processing.

A successful HTTP delivery means the endpoint accepted the event, not that its downstream processing succeeded.

Controls and options

• Enter an HTTPS endpoint and signing secret, or let the system generate a secret.
• Choose the event types the receiver actually needs, then Add webhook.
• Inspect deliveries for response codes and retry history; replay a failed attempt after fixing the receiver.
• Rotate a compromised secret and confirm the receiver accepts the new signature.

EPCIS subscriptions (/settings/epcis)

An EPCIS subscription pushes matching lifecycle events to a standing partner endpoint.

Define a destination and narrow the subscription query so a partner receives only relevant GTINs, categories, steps, dispositions, or event types. Send a sample to confirm endpoint and signature handling, then inspect deliveries during live use. Backfill and replay can resend events, so the receiver must deduplicate by event identity.

Subscribers should deduplicate by event identity; delivery is retried.

Controls and options

• Name the subscription, set Destination URL and optional signing secret.
• Limit the query by category, GTIN, event type, business step or disposition.
• Create the subscription and send a sample before depending on live delivery.
• Inspect the log, bounded backfill and replay controls when a receiver misses events.

Integration hub (/integration-hub)

Mappings translate ERP, PIM or PLM records into product fields, passport paths or component lines using a declared key and transforms.

Define how one source record identifies a product before mapping fields, then preview the transformation on a representative file. Record-to-field and bill-of-material mappings have different row meanings, so choose the kind that matches the source. Keep feed credentials in their dedicated fields and apply a run only after reviewing proposed writes and validation errors.

Applied differences pass schema validation and become audited passport versions.

Controls and options

• Start from a template or blank mapping; choose records or BOM kind and CSV, JSON or XML source.
• Select SKU or GTIN key field and source column, then add source-to-target rules with transforms and optional value maps.
• Configure optional HTTPS or SFTP feed and manual, hourly or daily schedule; credentials are write-only.
• Save mapping, then preview a sample before any write.

Mapping detail (/integration-hub/[id])

A saved mapping has preview, execution, feed and push controls plus run history.

Preview a file or feed against the saved mapping and inspect record-level matches, proposed differences, and rejections. Run the mapping only when the preview matches the intended products; changed passport data creates audited revisions. After a run, compare applied and skipped counts, then use history to investigate a particular source row without editing earlier provenance.

Do not paste source credentials into support messages or free-text mapping fields.

Controls and options

• Upload a source file and Preview changes to inspect per-record matches, errors and proposed writes.
• Run only after reviewing; changed passport fields create new versions, while unchanged values are skipped.
• Feed and push can fetch a scheduled source or issue a scoped push token for the source system.
• Edit rules and Save mapping with revision protection; inspect Run history for applied and rejected rows.
• Delete mapping requires confirmation and does not erase earlier run provenance.