Security and data protection
How BatteryPass protects API access and passport data, and what your integration should do and avoid.
This page describes the technical measures that apply to integrations and what you are responsible for on your side. It is a description, not a certification or an audit statement.
Transport
Production installations of BatteryPass are served over HTTPS; the reference deployment terminates TLS at its
reverse proxy and sends Strict-Transport-Security. Send API keys only to your BatteryPass address over HTTPS, and do not disable
certificate checks in your HTTP client.
API keys
| Measure | Detail |
|---|---|
| Secret | bp_live_ followed by 43 base64url characters (32 random bytes) |
| Storage | BatteryPass stores only the SHA-256 of the key. The key is shown once, when an owner creates it in the portal; it cannot be displayed again. |
| Recognition | The first 12 characters (bp_live_ and four more) are kept as a prefix, so owners can tell keys apart in the portal. |
| Header only | Keys are accepted only in Authorization: Bearer, never in a URL. A request that carries both a session cookie and a key is refused with 401. |
| Lifetime | Keys have no expiry. Revoking is the only way to stop one; a revoked key never works again. Rotate by creating a new key and revoking the old one. |
| Number | At most 25 active keys per organisation. |
Owners create and revoke keys in the portal and see when each key was last used. See Authentication and Secure key handling.
What a key may do
- Scopes. A key has one or more of
read,conditionandimport. Each operation names its scope inx-api-key-scope; a key without that scope gets403 forbidden. Give each system only the scope it needs. - Viewer rights. A key acts in its organisation with the rights of a viewer. It never changes declared data, approves values, publishes or withdraws passports, and never manages members, keys or settings.
- Organisation isolation. Every request is scoped to the key's organisation. Ids of another organisation's
resources behave as if they did not exist (
404 not_found).
Rate limits
| Limit | Applies to |
|---|---|
| 600 requests per minute | All keys of one organisation together |
| 30 attempts per 15 minutes | Unknown or revoked keys, per client address |
| 300 requests per minute | Public passport reads, public documents and the resolver, per client address |
A limited request gets 429 rate_limited with a Retry-After header in seconds
(Rate limits).
Audit
Every write made with a key (a condition update or a lifecycle event) is recorded in the organisation's audit
log with the actor api_key and the key's id, in the same transaction as the change. The values and events it
creates carry source api; the lifecycle event of each update names the key (api_key). Creating and revoking keys is audited with the member who did
it. Reads with a key are not audited.
Passport data
- Public operations and the resolver serve only the stored
publicprojection of a version (Access tiers). Restricted tiers never appear in a public response, and restricted documents are never linked from one. - Reading restricted tiers as a third party is a separate portal feature behind a switch that is off by default; every such read is audited.
- Each published version is signed, so changes after publication are detectable (Signatures).
- Errors are Problem Details with a stable
codeand arequest_id; they contain no SQL, stack traces or upstream error texts (Errors).
Data protection for integrations
BatteryPass is about batteries, not people, and your integration should keep it that way.
Do not send personal data in free text: the note of a condition update and the description of a lifecycle
event. Write "Module 3 replaced" rather than the technician's or the end customer's name, address, phone number
or vehicle registration. Events and measurements cannot be edited or deleted through the API, every member of
your organisation can read them, and they are part of the organisation's full export.
What you read can contain personal data too: provenance names members (recorded_by, reviewed_by,
responsible, published_by_name), and an event reported by a service partner can carry the partner's email
address. If your integration copies such data into another system, that system needs a legal basis and a
retention rule for it. Copy only what you need.
This documentation
The documentation pages load no analytics, advertising or third-party tracking scripts. The menu entries that open a page in an AI assistant send the page's address to that service only when you click them.
Reporting a security problem
If you suspect a key has leaked, ask an owner of your organisation to revoke it at once and create a new one. Report a suspected vulnerability directly to the operator of your BatteryPass installation, not in a shared channel (Support).