1. Désigner le propriétaire de l’intégration

Ouvrez « Paramètres → Accès → Clients API » en tant qu’administrateur. Créez un client distinct pour chaque système externe et environnement : vous pourrez ainsi remplacer une clé ou désactiver un canal sans arrêter les autres. Saisissez un nom reconnaissable et un utilisateur propriétaire. La clé agit uniquement dans les limites des droits de cet utilisateur.

Sélectionnez « Écriture » pour la réception de données et « Lecture » pour les états, résultats et points de publication. L’écriture n’est disponible que pour les flux exécutables par le propriétaire ; la lecture, pour les flux qu’il peut consulter. La publication avec exécution à la demande exige aussi son droit d’exécution. Désactiver le propriétaire ou lui retirer un droit affecte immédiatement la clé.

2. Limiter la durée, l’accès réseau et la charge

Choisissez une date d’expiration, valable jusqu’à la fin de cette journée UTC et au maximum trois ans plus tard. Ajoutez les adresses IPv4/IPv6 ou réseaux CIDR autorisés, un par ligne. CIDR permet de désigner une plage d’adresses réseau. L’accès IP et HMAC sont indépendants : « Toute adresse IP » désactive le filtrage IP. La signature est activée par défaut ; il est recommandé de la conserver, surtout sans restriction IP. Fixez les requêtes par minute. La limite API globale de la section s’applique également.

Enregistrez le client et transmettez la clé générée par votre canal sécurisé. Ne la placez pas dans du code de navigateur, un dépôt public ou une URL. Data Bridge génère la clé ; les clés arbitraires personnalisées ne sont pas prises en charge. L’affichage d’une clé complète est audité. Utilisez une variable d’environnement pour les exemples et tests.

3. Signer la requête HTTP exacte

Transmettez la clé dans Authorization: Bearer ... ou X-API-Key. HMAC nécessite aussi X-UBC-Timestamp contenant des secondes Unix et X-UBC-Signature: v1=<hex>. Calculez HMAC-SHA256 avec la clé du client sur quatre valeurs séparées par des sauts de ligne : horodatage, méthode HTTP en majuscules, chemin avec chaîne de requête et empreinte SHA-256 hexadécimale des octets exacts du corps.

L’écart de l’horloge avec le serveur ne doit pas dépasser cinq minutes. Conservez l’ordre et l’encodage des paramètres ainsi que le préfixe de l’installation. Ne modifiez pas le corps après signature : un JSON formaté différemment possède une autre empreinte. Pour GET, hachez un corps vide. Le secret est la clé du client API, pas le secret de rappel.

4. Vérifier l’accès avec ping

Dans un environnement Python avec requests installé, définissez UBC_API_KEY et UBC_API_PING_URL. La seconde variable est l’adresse HTTPS complète de /api/v1/ping, avec le préfixe requis. Cet exemple prépare la requête avant de la signer afin d’utiliser le chemin encodé réel ; les redirections sont désactivées.

import hashlib, hmac, os, time
from urllib.parse import urlsplit
import requests

key = os.environ["UBC_API_KEY"]
url = os.environ["UBC_API_PING_URL"]
request = requests.Request("GET", url).prepare()
body = request.body or b""
if isinstance(body, str):
    body = body.encode("utf-8")
parts = urlsplit(request.url)
path = parts.path + ("?" + parts.query if parts.query else "")
timestamp = str(int(time.time()))
canonical = "\n".join([
    timestamp, request.method, path,
    hashlib.sha256(body).hexdigest()
])
signature = hmac.new(key.encode("utf-8"),
                     canonical.encode("utf-8"),
                     hashlib.sha256).hexdigest()
request.headers.update({
    "Authorization": "Bearer " + key,
    "X-UBC-Timestamp": timestamp,
    "X-UBC-Signature": "v1=" + signature,
})
with requests.Session() as session:
    response = session.send(request, timeout=30,
                            allow_redirects=False)
    print(response.status_code, response.text)

Vérifiez le client renvoyé, l’heure du serveur, l’expiration et les droits. Appelez ensuite GET /api/v1/flows et confirmez que seuls les flux convenus sont accessibles. Changer l’adresse nécessite une nouvelle signature. Pour POST, préparez le corps une fois, signez ses octets et envoyez exactement ces octets.

5. Nouvelles tentatives, rotation et diagnostic

Une signature n’est acceptée qu’une fois : sa répétition renvoie 409 API_SIGNATURE_REPLAY. Signez à nouveau chaque interrogation ou nouvelle tentative de livraison ; respectez Retry-After pour éviter de répéter un GET identique dans la même seconde. Conservez pour la livraison le même Idempotency-Key: il empêche une exécution en double, tandis que HMAC protège chaque requête HTTP individuelle.

401 concerne généralement la clé, l’expiration ou la signature ; 403, l’IP ou les droits ; 429, les limites de fréquence. Lisez le code précis de réponse et l’enregistrement d’audit. Les échecs d’authentification répétés bloquent temporairement l’adresse IP.

Pour une rotation, l’administrateur génère une nouvelle clé et enregistre le client : l’ancienne cesse de fonctionner. Dans « API → Mes clés API », si le rôle le permet, les propriétaires peuvent consulter et renouveler leurs clés ; cette rotation autonome prend effet immédiatement. Après remplacement, vérifiez ping et un scénario autorisé, puis supprimez l’ancien secret du système externe.

Pour un accès contrôlé à l’historique, utilisez GET /api/v1/flows/{flow}/runs. La liste des résultats d’une exécution terminée est disponible à /api/v1/flows/{flow}/results?run=latest; une table précise à /api/v1/flows/{flow}/results/{block}?format=json&offset=0&limit=100. Choisissez les identifiants dans la réponse plutôt que dans un autre exemple. Fixez une exécution précise lorsque vous lisez plusieurs tables d’un même résultat : latest peut changer après une nouvelle exécution. Ces routes nécessitent « Lecture » sur le flux, et chaque adresse et page exige sa propre signature.