---
title: "Register an in-product Aletheia voice session (DARK)"
method: POST
path: "/aletheia/voice/register"
tags: ["AletheiaVoice"]
---

# Register an in-product Aletheia voice session (DARK)

`POST /aletheia/voice/register`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/aletheia/voice/register`
- Auth: API key in cookie `mnemom_session`

DARK (MNE-1944): gated fail-closed by an R2 flag + allowlist, zero customer exposure until promoted. Mints an audience-scoped, short-lived `voice_grant_token` (`audience:"in_product"`) and populates the aletheia-voice per-call stash BEFORE the browser can dial Retell (register-before-dial), so a spoken turn authenticates to the governed runtime without replaying any customer or deck credential. When the flag is absent, the caller is unauthenticated, or the caller is not allowlisted, the endpoint returns an identical opaque 404 ("feature not present") and mints nothing — there is no oracle that the endpoint or a caller's allowlist status exists. Cookie/bearer-authed like any other customer route (not an `/internal/*` machine-auth surface); registered on the public spec so `preDispatchAuthGate` can classify it (issue #1519).

## Request body

- object
  - `context` string: Optional in-product grounding/context text (KB/page context). Capped server-side. Context text ONLY — never a customer or deck credential.

## Response `200`

Voice session registered. Returns the Retell web-call access token + call id for the browser SDK (the browser dials only after this response).

- object
  - `access_token` string, required: Retell web-call access token.
  - `call_id` string, required: Retell call id the minted token is bound to.

## Other responses

- `401`: Authentication required
- `403`: Cross-origin write refused (`cross_origin_rejected`). A state-changing request that carries the browser session cookie must come from a first-party origin (`Origin`, or failing that `Referer`) and must not send a form-style body (text/plain, urlencoded, multipart) the operation does not declare. Bearer and API-key callers are never subject to this check.
- `404`: Feature not present (DARK): flag absent, unauthenticated, or caller not allowlisted — an identical opaque response for all three (no existence / allowlist oracle).
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
- `502`: Upstream voice provider (Retell) or the voice backend failed.
- `503`: Voice is not configured on this deployment (reachable only past the flag/allowlist gate).

---

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