Autenticación de apps y agentes de IA

#API REST

La clave va en la cabecera X-API-KEY, o en Authorization: Bearer para un cliente que solo sabe enviar un token Bearer (si se envían ambas, gana X-API-KEY). Nunca en la URL: una clave en una query string acabaría en los registros de acceso de cada intermediario del camino. Solo HTTPS: una petición en http:// sin cifrar se rechaza con 403 https_required, nunca se redirige, porque una redirección dejaría viajar la clave sin cifrar en cada llamada. Si ves ese error, rota la clave que llevaba.

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

La comparación se ejecuta en tiempo constante, así que una clave errónea tarda exactamente lo mismo en rechazarse que una casi correcta.

#La ruta sin clave

Solo una ruta responde sin autenticación: /v1/health, que indica si el servicio está en marcha. Todo lo demás exige la clave. Dos rutas nunca se descuentan de la cuota mensual (solo se aplica el límite de velocidad): /v1/health y /v1/limits, los límites de tu clave. /v1/status (la frescura de los datos) y /v1/symbols (el catálogo de activos) pertenecen a la familia precio y volumen, abierta en todos los planes, y cuentan como cualquier otra llamada.

# 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

#Flujo WebSocket

Desde un servidor, la clave va en la cabecera X-API-KEY del handshake, exactamente como en REST. Una página web no debe tener tu clave, y un navegador no puede poner cabeceras en un WebSocket: la página abre el flujo con ?token=, un token de corta duración que tu servidor obtiene de POST /v1/ws/token. En ambos casos, la credencial se comprueba en el handshake, antes de que se abra la conexión.

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, llamada por tu servidor con su clave, devuelve un token y una url lista para abrir. Un token vale 60 segundos y abre UNA conexión: usado o caducado, se rechaza; pide uno nuevo para cada conexión y cada reconexión. Solo abre el WebSocket, nunca una ruta REST, y los permisos aplicados son los de la clave en el momento del handshake (una clave revocada entretanto ya no se conecta). Un plan sin el flujo recibe 403 plan_websocket; emitir un token no se descuenta de la cuota mensual.

# 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 sesión se abre ya autenticada: el primer mensaje puede ser la suscripción. Una credencial ausente recibe un 401 missing_api_key en el handshake; una clave desconocida o revocada, o un token inválido, caducado o ya usado, un 401 invalid_api_key; un plan sin el flujo un 403 plan_websocket; y no se establece nada. Un 503 en el handshake no tiene que ver con la clave: el servicio de flujo ha alcanzado su capacidad y hay que reintentar un poco más tarde. El límite de conexiones simultáneas del plan vale para toda la cuenta: la conexión de más se cierra con el código 4003. La antigua trama {"op": "auth", "api_key": "…"} sigue aceptándose y responde authenticated, pero es opcional.

Los parámetros ?token= y ?api_key= solo se aceptan en el handshake de WebSocket, nunca en las rutas REST, y la pasarela no registra la línea de petición de /ws. ?api_key= sigue funcionando para los clientes existentes, pero una clave en una URL acaba en el historial del navegador y en los registros de los proxies: usa la cabecera desde un servidor y el token en una página. Los detalles del protocolo están en la página Flujo WebSocket.

#Servidor MCP

El servidor MCP espera la misma clave, en la misma cabecera X-API-KEY, puesta en la conexión HTTP. Sin ella no se expone ninguna herramienta: el servidor rechaza por defecto en lugar de abrir por defecto.

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 forma exacta del archivo de configuración depende del agente de IA; el principio no cambia: una URL y una cabecera. Ver Servidor MCP.

#Lo que dice un rechazo

#Proteger y rotar la clave