Skip to content
Bloonio Relay

Auth Relay overview

The Auth Relay is a multi-tenant broker that lets any backend push approval prompts — TOTP, golden number, biometrics — to the Bloonio Authenticator mobile app, including when the app is closed, without ever holding the platform’s push credentials.

The problem it solves

Section titled “The problem it solves”

Bloonio Authenticator is a generic authenticator (like Google Authenticator or GitHub Mobile). A single device can be paired with any number of independent backends via a QR code scan. Each backend wants to push approval prompts to the device.

But mobile push notifications require platform credentials (FCM on Android, APNs on iOS). Those credentials are tied to the app, not to the backend — so they cannot be handed out to every tenant backend. The relay holds these credentials centrally; backends authenticate with HMAC-signed requests and ask the relay to push.

Backend A ─┐
Backend B ─┼─ signed HTTPS ─►  Auth Relay  ─ FCM ─►  Bloonio Authenticator (device)
Backend N ─┘                  (FCM credentials, tenant registry)

iOS push goes through APNs via the FCM proxy: the APNs authentication key (.p8) is dropped once into the Firebase console, then FCM relays to Apple. One credential, one code path.

The identity model

Section titled “The identity model”
  • Tenant — one per backend. Provisioned once, receives a tenant_id and a tenant_secret. The backend uses the secret to HMAC-sign every request.
  • Pairing — one per (tenant_id, user_socket_hash) pair. Created when a user pairs the app with a backend. The user_socket_hash already exists in the Bloonio system; the relay reuses it.
  • Device tokens — the FCM tokens registered against a pairing. A pairing can carry several tokens (multi-device).

The opaque relay_user_id identifier is the universal validator on the relay side — it’s the pivot you store and pass to sudo dispatches. See Tenancy & relay_user_id for the full model (inspired by Stripe Connect).

Relationship with bloonio_auth_api

Section titled “Relationship with bloonio_auth_api”

The Auth Relay is a transport broker: for the QR-login, sudo, and WebAuthn flows it validates the tenant’s request (HMAC #1), attaches the authenticated tenant context to it, then forwards it to bloonio_auth_api (signed with HMAC #2). auth_api is the source of truth for identity, validation groups, and passkey credentials; the relay only stores the tenant registry and the push routing tables locally (pairings + device tokens).

Tenant ── HMAC #1 ─►  Auth Relay  ── HMAC #2 ─►  bloonio_auth_api
                       (tenant registry,           (identity, groups,
                        pairings, FCM push)          passkey credentials)

Flow map

Section titled “Flow map”
Quickstart Provision a tenant and make your first signed call.
Tenant management Admin lifecycle: provision, update, rotate, suspend.
Pairing & devices prepare-pairing → pairing_proof → device_session_token.
Push & security alerts Approval challenges and passive notifications.
QR login Initiate and poll a QR-code login session.
Sudo (step-up) Sudo dispatch and the two-call protocol.
Passkeys (WebAuthn) Enrollment, sign-in, and credential management.
Python SDK RelayClient, AsyncRelayClient, and @sudo_required.

Before you code

Section titled “Before you code”
  1. Read Authentication (HMAC) — every tenant /relay/* request is signed with the same HMAC #1 recipe.
  2. Understand the tenant lifecycle: provisioning, the secret shown only once, rotation, suspension.
  3. If your calls come from a Python backend, skip the manual signing implementation and use the Python SDK.