Verification links

A link is a hosted verification: send someone a URL, they complete the check, you get the result. No backend, no frontend work.

Use it to trial the product, to verify one person over email, or to let a support agent re-verify someone. For production traffic inside your own product, create sessions from your backend.

Create

curl -X POST https://machine.cognau.com/api/v1/cockpit/verification-links \
  -H "Authorization: Bearer $COGNAU_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Acme onboarding, J. Doe",
    "clientReference": "user_4821",
    "expiresInDays": 7,
    "maxUses": 1,
    "redirectUrl": "https://acme.com/verified"
  }'

Field	Default	Notes
label	empty	For your eyes only; how you find the result later
clientReference	none	Your id for this person; lands on the webhook
expiresInDays	7	Capped at 30
maxUses	1	Single use is the safe default
redirectUrl	none	We append session_id and result

The response contains the full URL once. Only its hash is stored, so it can never be shown again. Copy it into your email at that moment or issue another.

Why a link and not a session

Sessions expire in minutes. A session baked into an email would be dead before the recipient opened it. A link is the durable object, valid for days, and it mints a fresh short-lived session at the moment somebody opens it.

Treat the URL as a credential

Anyone holding it can run one verification billed to you. The defaults exist for that reason: single use, always expiring, revocable instantly.

curl -X DELETE https://machine.cognau.com/api/v1/cockpit/verification-links/$ID \
  -H "Authorization: Bearer $COGNAU_SECRET_KEY"

A spent link returns 410 with a message you can show the recipient as-is ("This verification link has already been used"). Redemption is rate limited per IP.

No retries

If someone fails, the check is over. The widget offers no "try again", because every attempt is a billable verification and letting the end user restart at will is a way to spend your money and exhaust a multi-use link. Whether they get another attempt is your decision: issue another link.