---
title: "Exchange an API key for a short-lived media token"
method: POST
path: "/media/token"
tags: ["media"]
---

# Exchange an API key for a short-lived media token

`POST /media/token`

Exchange your permanent API key for a short-lived token that authenticates `/stream/` requests **without** any header, so native players (AVPlayer, ExoPlayer) can fetch media directly.

Call this from your **server**, never from the device — the point of the exchange is that your permanent key never ships inside an app binary.

**Usage:** append the token to any stream URL as a query parameter:

`GET /stream/videos/branded/squat.mp4?token=<token>`

**Scope:** the token is valid on `/stream/` paths only. It cannot read `/exercises`, `/routines`, or any other endpoint, and it cannot mint another token.

**Metering:** each `/stream/` request authenticated by a token counts against the originating key's quota exactly as a keyed request does. Revoking the key, or losing the subscription, invalidates every outstanding token immediately.

**Tier:** requires TESTING or above. BASIC is Playground-only.

**Rate limit:** this is a refresh endpoint, not a per-video call. Mint one token per session and reuse it until it expires.

## Response `200`

Successful Response

- MediaTokenResponse — A minted media token and its lifetime.
  - `token` string, required — Opaque, signed, media-only token. Append it to any /stream/ URL as ?token=<token>. Treat it as a credential: do not log it, and do not embed it in a shareable link.
  - `expires_in` integer, required — Token lifetime in seconds from issue. Mint a new token before this elapses; expired tokens return 401.

## Other responses

- `401` — Missing X-API-Key header
- `402` — Custom plan provisioned but checkout is not complete
- `403` — Invalid key, BASIC tier, or a token was supplied instead of a key
- `429` — Too many mint requests, or the monthly quota is exhausted
- `501` — Media token exchange is not enabled on this deployment

---

[API](https://skmtc.dev/musclewiki/apis/musclewiki-api.md) · [All operations](https://skmtc.dev/musclewiki/apis/musclewiki-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/musclewiki/musclewiki-api/revisions/fccb1308d3dc/schema)