Authentification des apps et agents IA

#API REST

La clé va dans l’en-tête X-API-KEY, ou dans Authorization: Bearer pour un client qui ne sait poser qu’un jeton Bearer (si les deux sont envoyés, X-API-KEY l’emporte). Jamais dans l’URL : une clé dans une chaîne de requête finirait dans les journaux d’accès de chaque intermédiaire sur le chemin. HTTPS uniquement : une requête en http:// clair est refusée en 403 https_required, jamais redirigée, car une redirection laisserait la clé voyager en clair à chaque appel. Si vous voyez cette erreur, remplacez la clé qu’elle portait.

curl -H "X-API-KEY: $BYTNODE_API_KEY" \
  "https://api.bytnode.com/v1/basis?symbol=ETHUSDT"

La comparaison s’exécute en temps constant : une clé fausse met exactement autant de temps à être rejetée qu’une clé presque juste.

#La route sans clé

Une seule route répond sans authentification : /v1/health, qui dit si le service est en marche. Tout le reste exige la clé. Deux routes ne sont jamais décomptées du quota mensuel (seule la limite de débit s’applique) : /v1/health et /v1/limits, les limites de votre clé. /v1/status (la fraîcheur des données) et /v1/symbols (le catalogue des actifs) appartiennent à la famille prix et volume, ouverte sur toutes les offres, et comptent comme n’importe quel autre appel.

# The only route that answers without a key.
curl https://api.bytnode.com/v1/health

# /v1/limits requires the key but is never counted against the quota.
curl -H "X-API-KEY: $BYTNODE_API_KEY" https://api.bytnode.com/v1/limits

# /v1/status and /v1/symbols require the key and count as one request
# of the price & volume family, like any other call.
curl -H "X-API-KEY: $BYTNODE_API_KEY" https://api.bytnode.com/v1/status
curl -H "X-API-KEY: $BYTNODE_API_KEY" https://api.bytnode.com/v1/symbols

#Flux WebSocket

Depuis un serveur, la clé va dans l’en-tête X-API-KEY de la poignée de main, exactement comme en REST. Une page web ne doit pas détenir votre clé, et un navigateur ne peut pas poser d’en-tête sur un WebSocket : la page ouvre le flux avec ?token=, un jeton éphémère que votre serveur obtient de POST /v1/ws/token. Dans les deux cas, l’identifiant est vérifié à la poignée de main, avant que la connexion ne s’ouvre.

import asyncio
import json
import os

import websockets  # pip install websockets


async def main() -> None:
    # From a server, the key goes in the X-API-KEY header of the handshake:
    # the connection opens already authenticated. A missing or invalid key gets
    # 401 before it opens (a plan without the stream: 403).
    headers = {"X-API-KEY": os.environ["BYTNODE_API_KEY"]}
    async with websockets.connect("wss://api.bytnode.com/ws", additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "op": "subscribe",
            "channels": ["trades.futures.BTCUSDT"],
        }))
        print(await ws.recv())   # {"op": "subscribed", "channels": [...]}


asyncio.run(main())

POST /v1/ws/token, appelée par votre serveur avec sa clé, renvoie un token et une url prête à ouvrir. Un jeton vaut 60 secondes et ouvre UNE connexion : utilisé ou expiré, il est refusé ; demandez-en un neuf pour chaque connexion et chaque reconnexion. Il n’ouvre que le WebSocket, jamais une route REST, et les droits appliqués sont ceux de la clé au moment de la poignée de main (une clé révoquée entre-temps ne se connecte plus). Une offre sans le flux reçoit 403 plan_websocket ; émettre un jeton n’est pas décompté du quota mensuel.

# On YOUR server (the key stays there): issue a token for the browser.
curl -X POST -H "X-API-KEY: $BYTNODE_API_KEY" https://api.bytnode.com/v1/ws/token
# {"status":"ok", …, "data_type":"ws_token","data":{"token":"wst_…",
#  "expires_at":"…","expires_in_s":60,"url":"wss://api.bytnode.com/ws?token=wst_…"}}

La session s’ouvre déjà authentifiée : le premier message peut être l’abonnement. Un identifiant absent reçoit un 401 missing_api_key à la poignée de main ; une clé inconnue ou révoquée, ou un jeton invalide, expiré ou déjà utilisé, un 401 invalid_api_key ; une offre sans le flux un 403 plan_websocket ; et rien n’est établi. Un 503 à la poignée de main n’a rien à voir avec la clé : le service de flux a atteint sa capacité, il faut réessayer un peu plus tard. Le plafond de connexions simultanées de l’offre vaut pour tout le compte : la connexion de trop est fermée avec le code 4003. L’ancienne trame {"op": "auth", "api_key": "…"} reste acceptée et répond authenticated, mais elle est facultative.

Les paramètres ?token= et ?api_key= ne sont acceptés que sur la poignée de main WebSocket, jamais sur les routes REST, et la passerelle ne journalise pas la ligne de requête de /ws. ?api_key= fonctionne toujours pour les clients existants, mais une clé dans une URL finit dans l’historique du navigateur et les journaux des proxies : préférez l’en-tête depuis un serveur, le jeton dans une page. Le détail du protocole est sur la page Flux WebSocket.

#Serveur MCP

Le serveur MCP attend la même clé, dans le même en-tête X-API-KEY, posé sur la connexion HTTP. Sans elle, aucun outil n’est exposé : le serveur refuse par défaut plutôt que d’ouvrir par défaut.

import asyncio
import os

from fastmcp import Client  # pip install fastmcp
from fastmcp.client.transports import StreamableHttpTransport


async def main() -> None:
    transport = StreamableHttpTransport(
        "https://api.bytnode.com/mcp", headers={"X-API-KEY": os.environ["BYTNODE_API_KEY"]}
    )
    async with Client(transport) as client:
        info = await client.call_tool("get_system_info", {})
        print(info)


asyncio.run(main())

La forme exacte du fichier de configuration dépend de l’agent IA ; le principe ne change pas : une URL et un en-tête. Voir Serveur MCP.

#Ce que dit un refus

#Protéger et renouveler la clé