---
title: "Issue a passwordless, single-use magic-link token for the end-user memory portal (T424)"
method: POST
path: "/api/subjects/{subjectId}/magic-link"
tags: ["Subjects"]
---

# Issue a passwordless, single-use magic-link token for the end-user memory portal (T424)

`POST /api/subjects/{subjectId}/magic-link`

## Request

- Base URL: `http://localhost:38200`
- URL: `http://localhost:38200/api/subjects/{subjectId}/magic-link`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `token`

Tenant-authenticated -- the caller is the tenant's own backend, which knows the subjectId and is responsible for delivering the link to the end user (ContextQ has no notion of a subject's email address and sends no mail itself). The returned `token` is shown exactly once, single-use, and expires in 15 minutes; the caller embeds it into whatever URL/UI convention it wants pointing at its own frontend, which then exchanges it via the separate, unauthenticated `POST /api/subject-portal/verify` for a short-lived portal session. Always succeeds for a well-formed subjectId, whether or not that subject has any memories yet. See `docs/arch/subject-memory-portal-api.md` for the full contract. Rate limited to 5 requests / 10 minutes per (tenant, subjectId).

## Path parameters

- `subjectId` string, required

## Response `201`

Magic-link token issued.

- object
  - `subject_id` string
  - `token` string: Raw token, shown exactly once. Never persisted or re-derivable from the stored hash.
  - `expires_at` string, date-time

## Other responses

- `400`: subjectId is required.
- `401`: Missing or invalid credentials.
- `429`: Rate limit exceeded for this endpoint.

---

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