POST /v1/console/magic-link
| Call | POST /v1/console/magic-link |
| Price | free |
| Scope | none (public endpoint) |
| Operation id | requestMagicLink |
What it does
Section titled “What it does”Send a single-use sign-in link to an existing user’s email. The link works for 10 minutes, once, and only in the browser (user agent) that asked for it. Always answers 202 so it does not reveal which emails have accounts. Rate limited per IP and per email. No key or session needed. Passwords are not supported.
Example request
Section titled “Example request”Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.
curl -X POST 'https://api.askverdict.io/v1/console/magic-link' \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{ "email": "[email protected]"}'Example response
Section titled “Example response”202: A link was sent if the account exists.
{ "status": "sent", "expires_at": "2026-11-07T14:10:00Z"}Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
idempotency-key |
header | string (uuid) | yes | A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 idempotency_conflict. |
Request body
Section titled “Request body”Schema MagicLinkRequest. Who is signing in.
| Field | Type | Required | Description |
|---|---|---|---|
email |
string (email) | yes | The email of an existing Verdict user. |
Response fields (202)
Section titled “Response fields (202)”Schema MagicLinkResponse.
| Field | Type | Required | Description |
|---|---|---|---|
status |
enum: “sent” | yes | Always sent, whether or not the address has an account, so the endpoint does not reveal which emails are registered. |
expires_at |
string (date-time) | yes | When a link sent now expires. |
Errors
Section titled “Errors”Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.
| Status | Meaning |
|---|---|
400 |
Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request). |
401 |
Missing, malformed, revoked or expired API key, or a bad webhook signature (unauthorized). |
429 |
Rate limited (rate_limited). Wait Retry-After seconds. |
500 |
Unexpected server error (internal). Not billed; retry with the same Idempotency-Key. |
Try it
Section titled “Try it”Open the interactive reference to send this request from the browser. The full document is at /openapi.json.