<!-- Cognau documentation. Source: https://cognau.com/docs/verification-links -->

# 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](/docs/sessions) from your backend.

## Create

```bash
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.

```bash
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.