Signed URLs

Short-lived signed URLs for embeddable conversation audio playback.

When to use one

API keys are designed for server-to-server use. When you need to embed conversation audio in a customer-facing UI without proxying the bytes through your server, mint a short-lived signed URL on demand and hand it to the browser. The signed URL is scoped to one conversation, expires quickly, and carries no other authority. Losing it doesn't leak your API key.For real-time WebRTC conversations from a browser, use the WebRTC handshake (POST /conversation/connect → POST /conversation/:session_id/offer; trickle ICE via PATCH /conversation/:session_id/ice only if needed). There is no signed-URL transport for live WebRTC traffic.

Note

Signed URLs here are conversation-bound, not generic API tokens. They authenticate playback of one finished conversation's audio, not arbitrary API calls.

Conversation audio playback

Call GET /api/v1/conversations/{conversation_id}/audio from your server (scope: conversations:read) to get a short-lived signed URL for a finished conversation's audio. Hand the URL to the browser for direct playback. No audio bytes flow through your server.

Tip

The URL is signed with a short TTL. Generate it on demand when the user clicks Play, not at conversation-list time.

bash

curl https://api.aethexai.com/api/v1/conversations/{conversation_id}/audio \
  -H "X-API-Key: ae_live_..."

When a signed URL fails

If the token has expired or been tampered with, the audio request rejects with 401. Mint a fresh signed URL and retry. There is no refresh flow on purpose; the TTL is short.

401Unauthorized: invalid or expired token

The short TTL elapsed, or the token was tampered with in transit. Both produce the same 401.

Mint signed URLs at the moment the client is about to fetch the audio, not ahead of time. Don't cache them.

json

{
  "detail": "Invalid or expired audio token"
}

401Unauthorized: missing token and API key

The audio URL is missing its token parameter and no API key was supplied.

Always request the audio URL from your server — it will mint a fresh token on demand. Do not strip the query string.

json

{
  "detail": "Missing audio token or API key"
}