Démarrage rapide

Vous allez provisionner un tenant avec la clé admin, copier les trois identifiants qu’il renvoie, puis faire un premier appel signé (prepare-pairing). À la fin vous aurez un pairing_proof — le jeton court que vous transmettez à l’appareil pour démarrer un appairage.

Étape 1 — Provisionner un tenant

Seul tenant_name est requis. Tous les autres champs (limites de débit, origines QR-login, branding, configuration WebAuthn) sont optionnels au provisionnement et modifiables ensuite via /update/tenant.

curl $BASE_URL/api/v1/provision/tenant \
  -X POST \
  -H "X-Admin-Key: YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_name": "example_backend",
    "rate_limit_per_min": 120,
    "qr_login_allowed_origins": ["https://example.com"],
    "callback_url_base": "https://api.example.com",
    "branding_display_name": "Example",
    "branding_logo_url": "https://example.com/logo.png"
  }'

La réponse contient le tenant_secret — il est affiché une seule fois :

{
  "success": true,
  "status_code": 201,
  "message": "Tenant provisioned. Save tenant_secret now — it will not be shown again.",
  "data": {
    "tenant_id": "tnt_...",
    "tenant_secret": "sk_...",
    "tenant_name": "example_backend",
    "rate_limit_per_min": 120,
    "created_at": "2026-06-21T..."
  }
}

Étape 2 — Stocker les identifiants

Conservez les trois valeurs dans le .env du backend appelant :

RELAY_TENANT_ID=tnt_...
RELAY_TENANT_SECRET=sk_...
RELAY_BASE_URL=https://auth-relay.bloonio.com

Étape 3 — Faire un appel signé

Chaque appel /relay/* porte trois en-têtes HMAC. La signature est hex(hmac_sha256(tenant_secret, f"{ts_ms}.{sha256_hex(body)}")), l’horodatage est en millisecondes unix et doit être à ±30 s de l’heure du relais.

cURL
Python

# Calculez d'abord les en-têtes (voir l'onglet Python pour la recette
# complète), puis :
curl $BASE_URL/api/v1/relay/prepare-pairing \
  -X POST \
  -H "X-Bloonio-Tenant-Id: tnt_..." \
  -H "X-Bloonio-Timestamp: 1718966400000" \
  -H "X-Bloonio-Signature: <hex_hmac_sha256>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_socket_hash": "9f86d081884c7d659a2feaa0c55ad015",
    "backend_user_id": "507f1f77bcf86cd799439011",
    "user_email": "jane@example.com",
    "display_name": "Example"
  }'

import hashlib
import hmac
import json
import time

import requests

BASE_URL = "https://auth-relay.bloonio.com"
TENANT_ID = "tnt_..."
TENANT_SECRET = "sk_..."

body = json.dumps(
    {
        "user_socket_hash": "9f86d081884c7d659a2feaa0c55ad015",
        "backend_user_id": "507f1f77bcf86cd799439011",
        "user_email": "jane@example.com",
        "display_name": "Example",
    },
    separators=(",", ":"),
).encode()

ts_ms = str(int(time.time() * 1000))
body_sha = hashlib.sha256(body).hexdigest()
signature = hmac.new(
    TENANT_SECRET.encode(),
    f"{ts_ms}.{body_sha}".encode(),
    hashlib.sha256,
).hexdigest()

resp = requests.post(
    f"{BASE_URL}/api/v1/relay/prepare-pairing",
    headers={
        "X-Bloonio-Tenant-Id": TENANT_ID,
        "X-Bloonio-Timestamp": ts_ms,
        "X-Bloonio-Signature": signature,
        "Content-Type": "application/json",
    },
    data=body,  # IMPORTANT : envoyez exactement les octets signés
    timeout=10,
)
resp.raise_for_status()
print(resp.json()["data"]["pairing_proof"])

Vous obtenez en retour, en cas de succès :

{
  "success": true,
  "status_code": 201,
  "message": "Pairing prepared. Forward pairing_proof to the device.",
  "data": {
    "pairing_proof": "eyJhbGciOi...",
    "expires_in": 300
  }
}

Et après ?

Terminez l’appairage. Transmettez le pairing_proof à l’appareil, qui l’échange contre un device_session_token. Voir Appairage & appareils.
Poussez des challenges. Une fois l’appareil appairé, envoyez des invites d’approbation avec Push & alertes de sécurité.
Évitez de signer à la main. Si votre backend est en Python, le SDK Python gère la signature HMAC, le protocole sudo et les callbacks pour vous.