> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngnmarket.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Authentication

> How your API key travels over a WebSocket handshake, and how rejections work.

WebSocket authentication uses the same API keys as the REST API. There's no separate credential to generate. See [REST Authentication](/authentication) if you don't have a key yet.

## Pass your key as a query parameter

Browsers don't let client code set a custom `Authorization` header on a WebSocket handshake, so the key travels in the URL instead. Other market-data WebSocket APIs take the same approach:

```
wss://api.ngnmarket.com/v1/ws/prices?api_key=ngm_live_YOUR_KEY&symbols=DANGCEM,GTCO
```

<Warning>
  Because the key sits in the URL, avoid connecting to a WebSocket channel directly from client-side browser code in a production app. It can end up in browser history, proxy logs, or referrer headers. Proxy the connection through your own backend instead, the same way you'd avoid embedding a REST API key in frontend code.

  See [Proxy a WebSocket connection through your backend](/guides/websocket-proxy) for a working example.
</Warning>

## What happens on a bad key

If the key is missing, invalid, revoked, or restricted, the server rejects the handshake with a normal HTTP status code and a JSON error body, then closes the connection. It never accepts the WebSocket and disconnects you afterward:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key not found, revoked, or malformed."
  }
}
```

The same checks that protect REST requests apply to the handshake, in this order:

1. The key has to be present and valid, or you get `MISSING_API_KEY` or `INVALID_API_KEY`.
2. If your key has an IP allowlist configured, the connecting IP has to match it, exactly like REST. Otherwise you get `IP_NOT_ALLOWED`. Keys with no allowlist entries accept connections from any IP.
3. The key's plan has to meet the channel's requirement. Every plan, including Free, can open WebSocket connections today, so this check doesn't actually block anyone right now. `PLAN_REQUIRED` is there for if that changes later.

See [Errors](/websocket/errors) for the full list of codes, including the ones specific to WebSocket connections, like exceeding your connection or symbol limit.

<Note>
  Key checks run once, at connection time. Revoking a key from your [developer dashboard](https://ngnmarket.com/developer) immediately blocks any new connection attempt with it, same as REST. But a connection already open when you revoke stays open until it disconnects on its own, whether you close it or the network drops it.

  If a key is compromised and you need its open connections cut right away, close them yourself from wherever you opened them, right after revoking.
</Note>