Authentication

How to get an API key, connect to the WebSocket, authenticate, and what each close code means.

You authenticate with an API key from your dashboard. The key goes in the first text frame you send after the socket opens. It never goes in the URL.

Get a key

Open Dashboard, then API.

Button	What it does
Enable API	Turns the API on. The first time, it also creates your key.
Disable API	Turns the API off and closes your live socket. Your key stays, but it is refused while the API is off.
Regenerate	Creates a new key. The old key stops working at once. Closes your live socket.

The key is 64 hexadecimal characters. NextQuest shows it once: after your first Enable, and after each Regenerate. If you leave the page without copying it, regenerate to get a new one.

Disabling keeps your key. Enable API turns the API back on with that same key, so your tool needs no change. Only Regenerate makes a new key.

NextQuest stores only a SHA-256 hash of the key, so support cannot recover it for you. Letter case does not matter when you authenticate.

Important

Regenerating signs you out of every other NextQuest session. The browser where you click the button stays signed in. Sign in again on your other devices. Enable API never signs anyone out.

Connect

wss://<host>/api/ws

Always use wss://. The app code does not check how you connected, so a ws:// connection may work on some hosts. It would send your key in plain text. Do not use it.

Do not put the key in the URL. Any request with a token query parameter is refused with HTTP 401, even if the key is right.

Send the first frame

Send one text frame within 10 seconds of the socket opening:

{"type":"authenticate","apiKey":"YOUR_64_CHARACTER_KEY"}

Rules for this frame:

It must be a text frame. A binary frame closes the socket.
It must be 4096 bytes or smaller in total.
It must be valid JSON with type set to authenticate and apiKey set to a string of 64 hex digits.

On success the server sends no reply. Events start arriving when something happens on your boards. The server only sends event frames and empty keepalive frames. See WebSocket connection.

Limits

Each client address can have at most 5 sockets that have connected but not yet authenticated. A sixth attempt gets HTTP 429 and no socket opens. For IPv6, all addresses in the same /64 range count as one client. A socket stops counting as soon as it authenticates or closes.

If you hit 429, close the sockets that never authenticated, or wait for them to time out after 10 seconds.

Errors and close codes

What happens	What you see
The request is not a WebSocket upgrade	HTTP 400
The URL has a `token` parameter	HTTP 401, no socket
5 sockets from your address are still waiting to authenticate	HTTP 429, no socket
The first frame is binary	Close 1008, reason `Authentication must be text.`
The first message is over 4096 bytes	Close 1008, reason `Authentication message too large.`
The payload is not the expected JSON, or the key is not 64 hex digits	Close 1008, reason `Invalid authentication payload.`
The key is wrong, old, or the API is disabled	Close 1008, reason `Authentication failed.`
You send nothing for 10 seconds	The connection drops. See the note below.
You disable the API while connected	Close 1000, reason `API disabled`
You regenerate the key while connected	Close 1000, reason `API key regenerated`

Note

On a 10-second timeout the code tries to send close 1008 with the reason Authentication timed out. In a local test the server's socket was already aborted by that point, so the close frame was not sent. Browsers report this as code 1006 with no reason. Treat 1006 during connect as a timeout and check that your first frame goes out right after the socket opens.

A wrong key and a disabled API give the same reason. The server does not tell you which one it was.

Keep your key safe

Store the key in your tool's secret settings, not in a public repository or an overlay URL.
A browser-source overlay on a public web page exposes the key to anyone who views the source. Run the connection from a local tool instead.
If you think a key leaked, select Regenerate. The old key stops working at once.

Next: how the connection behaves, then Examples.