Authentication for Apps and AI Agents

#REST API

The key goes in the X-API-KEY header, or in Authorization: Bearer for a client that can only set a bearer token (when both are sent, X-API-KEY wins). Never in the URL: a key in a query string would end up in the access logs of every intermediary along the way. HTTPS only: a request over plain http:// is refused with 403 https_required, never redirected, because a redirect would let the key travel unencrypted on every call. If you ever see that error, rotate the key it carried.

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

The comparison runs in constant time, so a wrong key takes exactly as long to be rejected as an almost-right one.

#The route without a key

Only one route answers without authentication: /v1/health, which says whether the service is up. Everything else requires the key. Two routes are never counted against the monthly quota (only the rate limit applies): /v1/health and /v1/limits, the limits of your key. /v1/status (the freshness of the data) and /v1/symbols (the asset catalogue) belong to the price and volume family, open on every plan, and count like any other call.

# 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

#WebSocket stream

From a server, the key goes in the X-API-KEY header of the handshake, exactly as in REST. A web page must not hold your key, and a browser cannot set a header on a WebSocket: the page opens the stream with ?token=, a short-lived token your server obtains from POST /v1/ws/token. Either way, the credential is checked at the handshake, before the connection opens.

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, called by your server with its key, returns a token and a ready-to-open url. A token is valid 60 seconds and opens ONE connection: once used or expired it is refused, so request a new one for each connection and each reconnection. It opens the WebSocket only, never a REST route, and the rights applied are those of the key at the moment of the handshake (a key revoked in between no longer connects). A plan without the stream gets 403 plan_websocket; issuing a token is not counted in the monthly quota.

# 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_…"}}

The session opens already authenticated: the first message can be the subscription. A missing credential gets a 401 missing_api_key at the handshake; an unknown or revoked key, or an invalid, expired or already used token, a 401 invalid_api_key; a plan that does not include the stream a 403 plan_websocket; and nothing is established. A 503 at the handshake has nothing to do with the key: the stream service has reached its capacity, and the connection should be retried a little later. The plan’s ceiling on simultaneous connections applies to the whole account: the connection too many is closed with code 4003. The old frame {"op": "auth", "api_key": "…"} is still accepted and answers authenticated, but it is optional.

The ?token= and ?api_key= parameters are only accepted on the WebSocket handshake, never on the REST routes, and the gateway does not log the request line of /ws. ?api_key= still works for existing clients, but a key in a URL ends up in browser history and proxy logs: prefer the header from a server and the token in a page. The details of the protocol are on the WebSocket stream page.

#MCP server

The MCP server expects the same key, in the same X-API-KEY header, set on the HTTP connection. Without it, no tool is exposed: the server refuses by default rather than opening by default.

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())

The exact shape of the configuration file depends on the AI agent; the principle does not change: a URL and a header. See MCP server.

#What a refusal says

#Protecting and rotating the key