API keys
How heliumOS Wi-Fi offload keys are issued, scoped, and rotated.
Every request authenticates with an API key sent in a custom header:
X-Helium-P-API-Key: pk_live_...
The gateway takes the header, resolves it to your partner ID, and forwards the request to the inventory service. From your side it looks like a single API call.
Treat keys like database passwords. Never embed one in a client-side bundle, commit it, or paste it into logs. The mobile SDK reads the key from
process.envat startup, which is fine if you build it into the bundle and not fine if you log the resolved config.
Getting a key
Keys are issued white-glove by Helium. Email your account owner with:
- The partner ID you want the key scoped to.
- A human-readable label for the key, saying where it will live (for example "Acme prod backend").
- Which role you need (see roles below).
You'll receive the key out of band. Confirm receipt and store it in your secrets manager.
A self-service partner dashboard is on the roadmap. Until then, ask your account owner for any key, role, or environment change.
Roles
Each key is assigned a role at issuance time. There are two:
| Role | Use for | Grants |
|---|---|---|
| Partner SDK | Keys embedded in your mobile app via @helium/passpoint-sdk. | Generate and query Passpoint profiles for your subscribers. |
| Partner Admin | Keys used by your backend to manage subscribers end to end. | Everything in Partner SDK, plus: create, read, and revoke subscribers; read your partner record; issue and rotate access-point certificates. |
Pick the narrowest role that fits the caller. The SDK in a mobile bundle should always use a Partner SDK key. A Partner Admin key in a shipped app would let anyone who extracts it mutate your subscriber list.
If you need a different combination, talk to your account owner. Custom roles are possible, but the two above cover every production integration today.
Compromise response
If you suspect a key has been exposed:
- Email your account owner with the subject "Wi-Fi offload key compromise", including the key ID or label and the time window of suspected exposure.
- Helium revokes the key. Any in-flight requests using it start
failing with
401. - You'll receive a fresh key. Replace it in your services, then audit your logs for unexpected use of the compromised one.