Authentication

Cognau uses three credentials. Confusing them is the most common integration mistake, so it is worth two minutes.

Credential	Looks like	Lives	Grants
API key	cgn_sk_live_… / cgn_sk_test_…	your server, only	full account access
Session token	cgn_st_…	the browser	one WebSocket, once
Link token	cgn_vl_…	an email or URL	one session, then spent

API keys

Send as a bearer token:

curl https://machine.cognau.com/api/v1/cockpit/sessions \
  -H "Authorization: Bearer cgn_sk_live_…"

The key decides both who you are and which environment you are in. A test key cannot create live sessions and a live key cannot create sandbox ones, so a misconfigured deployment fails loudly instead of quietly billing you.

Never put an API key in a browser. It grants read access to every session on your account. Only the hash is stored on our side, so a key is shown in full exactly once, at creation; if you lose it, issue another and revoke the old one.

Multiple active keys per environment are allowed on purpose, so rotation is create → deploy → revoke, with no window where your integration is down.

Session tokens

Returned by POST /session/create and handed to the browser. A session token authorizes exactly one WebSocket connection and nothing else. It is single-use: once a socket opens, the token is spent, which is why a dropped connection ends the session rather than resuming it.

Link tokens

The credential inside a verification URL. Weaker than an API key by construction: it can create the one session it is scoped to, and cannot read verdicts, list sessions, or see anything about your account.

Treat the URL itself as the secret. Anyone holding it can run one verification that you are billed for, which is why links default to a single use, always expire, and can be revoked instantly.