The security model of an ERP integration

An integration between your ERP and BatteryPass moves data that ends up in signed, public battery passports. This page collects the rules that keep that path safe. Most of them are on your side of the connection; where BatteryPass enforces something itself, it says so. Key handling in day-to-day operation is described in Handle keys securely.

Keys and scopesCopy Anchor Link

One key per integration and per environment. A test middleware and the production middleware get different keys, and so do two integrations that run in the same middleware. You can then revoke one without stopping the others, and the portal's Last used column tells you which one is active.

The smallest scope that works. A key has one or more of three scopes:

No scope lets a key commit an import, approve a value, publish, withdraw, manage members or keys, or change declared data. Those stay with members of your organisation in the portal. A key acts with the rights of a viewer plus its scopes, and it is never limited to some units: a condition key can report for every unit of your organisation.

SecretsCopy Anchor Link

• Keep each key in a secrets manager or vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, the iPaaS's credential store) and hand it to the process at start. Never put it into code, configuration under version control, container images, URLs, logs or tickets. The OWASP Secrets Management Cheat Sheet describes the practice in detail.
• Send the key only in the header Authorization: Bearer bp_live_…. A request that also carries a portal session cookie is refused, so the actor is never ambiguous.
• Mask the Authorization header in every log of your middleware and HTTP client.

Rotation. Keys do not expire. Rotate them on your own schedule and whenever someone who knew a key leaves: create a new key with the same scopes, switch the middleware to it, check that the new key shows a recent Last used time, then revoke the old one. Both work at the same time during the switch, so nothing fails. Revocation is immediate and final.

TransportCopy Anchor Link

• Call BatteryPass only over HTTPS (TLS) and verify the server certificate. Do not turn verification off in test environments either: a middleware configuration tends to travel from test to production.
• Egress allow-listing as a second line: let the middleware reach only the BatteryPass address and the ERP. It does not replace keys and TLS, but it limits what a compromised middleware can talk to.
• The same goes the other way: expose the ERP's APIs to the middleware only, never directly to the internet.

Retries that do not duplicateCopy Anchor Link

Networks fail. A request that timed out may or may not have been carried out, so retries must be safe.

Back off. Retry network errors and 5xx answers with exponential backoff and jitter (for example 1, 2, 4, 8 seconds plus a random part, at most five attempts). Answer 429 rate_limited by waiting the seconds of the Retry-After header; all keys of your organisation share 600 requests per minute. Do not retry other 4xx answers: the request was refused as a whole, so fix it. Details are in Handle errors and retries and Rate limits.

Make each retry safe. BatteryPass accepts an Idempotency-Key header only on bulk and publishing operations of the portal, which keys cannot call. For the operations a key uses, the safety comes from the operations themselves and from your middleware:

The IETF is working on a general Idempotency-Key header (draft-ietf-httpapi-idempotency-key-header, draft 08, not yet an RFC). It is useful background for your own APIs; BatteryPass does not accept it on the operations above.

The outbox on the ERP sideCopy Anchor Link

The ERP must not lose a change while the middleware or BatteryPass is unreachable, and it must not call BatteryPass inside its own business transaction. The transactional outbox solves both: in the same database transaction that posts the goods receipt, the ERP (or an extension of it) writes a row to an outbox table. The middleware reads the outbox, calls BatteryPass, and marks the row done only after a successful answer.

This gives at-least-once delivery: a row may be sent twice (after a crash between call and marking), never zero times. Combine it with the retry rules above, and keep a small table of what you already sent (source record, BatteryPass id, time) so you can de-duplicate on your side.

Thin events, then fetchCopy Anchor Link

Do not move data inside notifications. Both directions work the same way:

• From the ERP: many ERPs send thin events (a product number and the kind of change). The middleware reads the current record from the ERP's API afterwards, checks the vendor's signature, handshake or secret URL, and drops events it cannot verify.
• From BatteryPass: the change feed lists only {id, occurred_at, entity_type, entity_id, action}, never values, actors or personal data. The middleware reads the entity with the same key afterwards, so the feed reveals nothing on its own and is always current.

The feed returns a change only once every older transaction in BatteryPass has finished, so a stored cursor never skips a change that committed late. Store the cursor only after your side has processed the page. BatteryPass sends no outbound webhooks yet; they are planned and need a decision of their own (signing, subscription management, protection of target addresses). Until then, poll.

Stale writesCopy Anchor Link

Mutable resources carry a row_version. updateImportMapping requires If-Match: "<row_version>"; when someone else changed the import in between, the answer is 409 conflict and nothing is overwritten. Read the import again and decide. Condition data has its own rule: an older measurement never replaces a newer one.

Data minimisationCopy Anchor Link

The GDPR asks for data that is "adequate, relevant and limited to what is necessary" (Art. 5(1)(c)). For a battery passport that means data about the battery: serial number, model, dates, measurements, events. Customer names and addresses, order numbers, employee names, prices, vehicle and location data stay in the ERP. Each workflow lists what it sends and what it leaves out, and the overview lists what never flows.

Free text is where personal data slips in: an event description such as "repaired for Mr. X at Y" ends up in your battery's history. Fill descriptions from fixed codes or templates, not from free text of a service order.

The audit trailCopy Anchor Link

• Every write with a key is recorded in your organisation's audit log with the actor type api_key and the key's name: staging and validating an import, a condition update, a lifecycle event.
• Imports staged with a key name the key instead of a member (created_by_api_key), in the API and in the portal.
• Values written with a key do not carry the key themselves. A condition update creates a condition_update lifecycle event, and that event names the key (api_key).
• Condition data is stored as approved measurements without a reviewer. Declared data takes the reviewed path: imported values are approved by a reviewer, and whether a second person must approve is your organisation's four-eyes setting.
• Reads are not recorded. Assume that a leaked key's data was read.

OWASP API Security Top 10Copy Anchor Link

How the OWASP API Security Top 10 (2023) risks that matter most for an ERP integration are handled, and what remains your part: