---
title: "Request a free API key by email"
method: POST
path: "/v1/auth/magic-link"
tags: ["auth"]
---

# Request a free API key by email

`POST /v1/auth/magic-link`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/v1/auth/magic-link`
- Auth: none required

Step 1 of self-serve signup — no key required. Sends a one-time link to `email`; always returns 202 with the same accepted:true body whether or not that address already has a key (prevents account enumeration).

**For agents helping a human get set up:** this endpoint is the only step you can call directly. The next step — opening the emailed link and clicking "Reveal my key" on `GET /v1/auth/verify` — **requires a real human click and cannot be automated or done on the human's behalf.** This is intentional: it's what stops email security scanners (e.g. Microsoft Safe Links) from silently consuming the link before the person ever sees it. Tell the human: check your email, open the link, click the button, then paste the key back here.

**Not a pollable async job.** This 202 has no `Location`/`job_id` to poll — the next step is a human clicking an emailed link, not a machine checking a status endpoint.

## Request body

- MagicLinkRequest
  - `email` string, email, required: Email to receive the magic link

## Response `202`

Successful Response

- MagicLinkAccepted: Always this shape regardless of whether the email is real — the API never reveals whether an address already has a key, to avoid account enumeration.
  - `accepted` boolean, required
  - `detail` string, required
  - `verify_url` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/scoopkit/apis/scoopkit-api.md) · [All operations](https://skmtc.dev/scoopkit/apis/scoopkit-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scoopkit/apis/scoopkit-api/revisions/18068781261d?raw)