---
title: "Request passwordless email authentication"
method: POST
path: "/auth/v1/magic-link"
tags: ["Auth"]
---

# Request passwordless email authentication

`POST /auth/v1/magic-link`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/auth/v1/magic-link`
- Auth: one of:
  - API key in header `apikey`
  - API key in header `apikey` and HTTP bearer

Requests link, code, or both delivery for sign-in, invite, claim, or recovery. delivery defaults to link. redirect_url is required for link/both and optional for code. A syntactically valid anonymous request receives generic accepted wording regardless of account existence; acceptance does not claim provider delivery. code/both returns only an opaque challenge_id, never the code. intent=invite requires a service key and produces trusted state.

## Request body

- object
  - `email` string, email, required
  - `redirect_url` string, uri: URL to redirect to with ?token=<token>. Must be an allowed origin for this project and must be served by a document that exchanges the token. If the active release serves this path through a GET static route alias, the 200 response includes a MAGIC_LINK_REDIRECT_STATIC_ALIAS warning.
  - `delivery` 'link' | 'code' | 'both': Credential(s) included in the email. redirect_url is required for link/both.
  - `intent` 'signin' | 'invite' | 'claim' | 'recovery'
  - `client_state` unknown

## Response `200`

Request accepted. code/both may include an opaque challenge_id; warnings are preserved.

- AuthMagicLinkResponse
  - `message` string, required
  - `challenge_id` string, uuid: Opaque public handle returned for accepted code/both requests. Never the emailed code.
  - `warnings` object[]: Non-blocking configuration warnings. Present when redirect_url matches an active GET static route alias.
    - `code` 'MAGIC_LINK_REDIRECT_STATIC_ALIAS', required
    - `message` string, required
    - `path` string, required
    - `target_file` string, required

## Other responses

- `400`: Invalid delivery/input, missing redirect_url for link/both, or redirect_url not allowed
- `403`: Service key required for invite intent
- `429`: Rate limited (per-email or per-project)

---

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