Environments and base URL
Where your organisation's API lives, which addresses it serves and how to test safely.
Base URL
BatteryPass runs per deployment; there is no shared global API host. Your base URL is the BatteryPass address
of your organisation, the same address you use for the portal, for example https://batterypass.example.com.
The API lives under /api/v1 on that address.
Addresses
| Path on your BatteryPass address | What | Authentication |
|---|---|---|
/api/v1/... | The integration API | API key |
/api/v1/public/... | Public passport reads | None |
/api/v1/openapi.json, /api/v1/openapi.yaml | The published contract | None |
/01/{gtin}/21/{serial} | GS1 Digital Link resolver, the target of the QR codes | None |
/pass/{passportId} | Public passport page for browsers | None |
/.well-known/batterypass/keys.json | Public signing keys (JWK set) to verify passport signatures | None |
/docs/ | This documentation | None |
A deployment can print a separate resolver host into its QR codes. Take a unit's Digital Link from the
gs1_digital_link member of getPassport instead of
building it yourself. See GS1 Digital Link.
Conventions
- HTTPS. Send requests, and above all keys, only over HTTPS.
- JSON. Request and response bodies are UTF-8 JSON; send
Content-Type: application/jsonwith a body. Bodies are limited to 1 MiB by default (413 payload_too_large), and unknown properties are refused. - Times (
date-time) are UTC in RFC 3339, e.g.2026-10-24T02:00:00Z. Send times with an offset; UTC is the safest choice. - Dates (
date, e.g.occurred_on,manufacturing_date) areYYYY-MM-DDwithout a time zone. - Ids are UUID strings. The permanent passport identifier is
urn:dpp:{uuid}; public routes take only the UUID.
Configure your client
All samples read two environment variables:
| Variable | Value |
|---|---|
BATTERYPASS_URL | Your BatteryPass address without a trailing slash, e.g. https://batterypass.example.com |
BATTERYPASS_API_KEY | An API key of your organisation, bp_live_... |
export BATTERYPASS_URL="https://batterypass.example.com"
export BATTERYPASS_API_KEY="bp_live_..."Keep the key in a secret store or your platform's secret management, not in source code or in files you commit. See Secure key handling.
Testing
BatteryPass has no public sandbox. Test against an environment where mistakes do no harm:
- A separate test organisation, or a separate BatteryPass deployment, with its own keys. Data is always separated by organisation, so a test key never sees or changes production data. Ask the people who run your BatteryPass deployment to set it up.
- Do not test writes against production. A condition update by key can re-publish a public passport at once, depending on the organisation's settings, and lifecycle events cannot be deleted through the API.
- Mind what is public. Passports published in a test organisation are public too, at the same addresses. Do not use the GTINs of real products for test data, and do not print or hand out test QR codes.
- Separate configuration. Keep test and production values of
BATTERYPASS_URLandBATTERYPASS_API_KEYapart, and give test keys only the scopes the test needs.