Subscriber IDs
The contract between your subscriber records and Helium's certificate registry.
A subscriberId is an opaque string you pick to identify a
subscriber in your system. The SDK and backend don't interpret it
beyond requiring a non-empty string.
It's the join key between your records and Helium's: every certificate
is filed under the subscriber ID you passed to install().
Rules
- Use the same ID for
install()andgetRemoteStatus(). A mismatch looks like "no profile installed" even when one exists. - Keep it stable per subscriber across reinstalls. If a subscriber reinstalls your app, reuse their existing ID so server-side state (revocation, status, audit trail) carries over.
- Re-calling
install()with the same ID revokes the previous certificate server-side and issues a fresh one. This is the supported path for certificate renewal. - Use a fresh ID per subscriber. Reusing one ID across end-users conflates their certificates server-side.
IDs are not cryptographically validated. If your client picks the ID, an attacker who learns another subscriber's ID could request a fresh certificate in their name (the API key is still scoped to your partner record). Bind ID generation to your authenticated session; don't expose ID selection to the client UI.
Format suggestions
There's no required format. Pick whatever is most stable in your system:
| Source | Pros | Cons |
|---|---|---|
| Internal user UUID | Stable, opaque. | Needs a server lookup to recover the human. |
| Phone number (E.164) | Globally unique, intuitive. | PII; phone reuse is real; rotation is hard. |
| Hash of a stable identifier | Opaque, stable, no PII leak. | You track the hashing scheme yourself. |
| Partner-issued account number | Aligns with your CRM. | Renumbering kills server-side continuity. |
A reasonable default: <your-partner-prefix>:<internal-user-uuid>.
Migration and churn
If a subscriber's ID changes, because you renumbered accounts or changed CRMs:
- Call the revocation API with the old ID to clear the server-side certificate.
- Have the device call
sdk.remove()to clear the local profile. - Call
install(newId)to provision under the new ID.
Doing only step 3 leaves an orphan record under the old ID, which counts against any per-partner subscriber quotas.
Privacy
The ID lives in:
- The certificate's CN / subject, visible to RADIUS infrastructure.
- Inventory-service logs.
- Your own logs.
Don't put anything in it you wouldn't want to see in a network trace. Treat the ID as semi-public.