POST /v1/console/magic-link/consume

Call	POST /v1/console/magic-link/consume
Price	free
Scope	none (public endpoint)
Operation id	consumeMagicLink

What it does

Exchange the token from a sign-in or invitation link for a console session, set as the httpOnly verdict_session cookie. The token is single use, expires 10 minutes after it was sent and must come from the same user agent that requested it; otherwise 401. An invitation link also adds the user to the inviting organization (creating the user if needed). No key or session needed.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

Request

curl -X POST 'https://api.askverdict.io/v1/console/magic-link/consume' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "token": "Ex4mpleMagicLinkTokenFromTheEmailLink00000001"
}'

Example response

200: Signed in; the cookie is set.

200 response

{
  "user": {
    "id": "usr_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
    "email": "[email protected]",
    "totp_enabled": false
  },
  "orgs": [
    {
      "id": "org_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
      "name": "Northwind Ops",
      "slug": "northwind-ops",
      "role": "owner",
      "created_at": "2026-11-01T09:00:00Z"
    }
  ],
  "mfa_verified": false,
  "idle_expires_at": "2026-11-14T14:00:00Z"
}

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

Schema ConsumeMagicLinkRequest. The link token.

Field	Type	Required	Description
token	string	yes	The token from the sign-in or invitation link.

Response fields (200)

Schema ConsoleSession.

Field	Type	Required	Description
user	ConsoleUser	yes	A console user.
user.id	string	yes	User id.
user.email	string (email)	yes	The user’s verified email.
user.totp_enabled	boolean	yes	Whether TOTP is turned on.
orgs	array of ConsoleOrg	yes	Organizations the user belongs to.
orgs[].id	string	yes	Organization id.
orgs[].name	string	yes	Organization name.
orgs[].slug	string	yes	URL-safe organization slug.
orgs[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The user’s role in this organization.
orgs[].created_at	string (date-time)	yes	When the organization was created.
mfa_verified	boolean	yes	Whether this session has passed TOTP. When the user has TOTP on and this is false, org actions answer 401 until POST /v1/console/totp/verify succeeds.
idle_expires_at	string (date-time)	yes	When the session expires if it is not used again (7 days after last use).

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

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.