> ## Documentation Index > Fetch the complete documentation index at: https://docs.alakazam.gg/llms.txt > Use this file to discover all available pages before exploring further. # Exchange a session token for a runtime connect token > Called from the EMBED'S BROWSER with the session token (the token IS the auth — no API key). Admits the session under your per-tenant + the global concurrency caps and your daily session-minutes budget, then returns a short-lived runtime connect token plus the world to play. All cost controls are enforced here. ## OpenAPI ````yaml /alakazam-v1.yaml post /v1/sessions/connect openapi: 3.1.0 info: title: Alakazam — Programmable Worlds API version: '1.0' description: > **Alakazam is the programmable worlds API.** Generate playable, AI-rendered worlds from a prompt or an image, program their logic, and embed them in your own products and games. A world is *programmable*: a live graph of states and events you generate, then read, edit, fork, drive, and react to through the API. Two surfaces: a **Creation API** (generate, read, manage, fork worlds) and a **Runtime/Embed API** (mint short-lived session tokens your end-users' browsers use to boot an embedded world). **Authentication.** Two schemes. Management endpoints (`/v1/apps*`) use your Supabase user session. Data endpoints use an **API key** issued per app: `pk_…` (publishable, browser-safe, read + embed) and `sk_…` (secret, server-only, create worlds + mint sessions). Never ship a secret key to a browser. **Usage & quota.** Generations and session mints are metered per app and reserved before any GPU spend; exceeding the daily quota returns `402`. servers: - url: https://api.alakazam.gg description: Production (placeholder — set to your conjure-service host) security: [] tags: - name: Apps & Keys description: >- Create apps (tenants) and manage API keys. Authenticated with your user session. - name: Worlds description: >- Create, read, manage, and fork SMWorld games. Authenticated with an API key. - name: Graph editing description: > Read and program a world's graph — states (nodes), events (edges), and the entrance — with deterministic CRUD, a batch op vocabulary, a natural-language kernel-agent edit, and the kernel validate/lint gate. Every write is validated fail-closed before it persists. Authenticated with an API key. - name: Versions description: > Snapshot, branch, check out, and diff a world's graph. Versions form a branching tree of full snapshots; a HEAD pointer tracks the working graph. Authenticated with an API key. - name: Characters description: > Create, manage, and talk to characters — a SMWorld subtype that pairs a stance-graph with a "brain" (persona, lore, voice). CRUD is authenticated with an API key; the live talk turn (/say) and voice (/tts) are called from the browser with a short-lived session token. - name: Sessions description: Mint short-lived runtime tokens for embedding a world. - name: Usage description: Per-app usage and quota. - name: Webhooks description: >- Register HTTPS endpoints to receive signed server-side event notifications. Managed with your user session. paths: /v1/sessions/connect: post: tags: - Sessions summary: Exchange a session token for a runtime connect token description: > Called from the EMBED'S BROWSER with the session token (the token IS the auth — no API key). Admits the session under your per-tenant + the global concurrency caps and your daily session-minutes budget, then returns a short-lived runtime connect token plus the world to play. All cost controls are enforced here. requestBody: content: application/json: schema: type: object properties: token: type: string description: 'The session JWT (or send it as Authorization: Bearer).' responses: '200': description: A runtime connect token + the world. content: application/json: schema: type: object properties: worldId: type: string format: uuid description: >- The resource id (for a character, the /v1/characters/{id} to talk to). reactorJwt: type: string expiresIn: type: integer expiresAt: type: integer nullable: true world: type: object description: >- The SMWorld to play. For a character, world.kind=='character' and world.character carries the render-safe brain (stances/voice/greeting/intro) — never the persona/lore. '401': description: Invalid or expired session token content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Daily session-minutes exhausted content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: World not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Live session capacity reached content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Runtime not configured content: application/json: schema: $ref: '#/components/schemas/Error' security: - SessionToken: [] components: schemas: Error: type: object properties: detail: type: string description: Human-readable error message. errors: type: array items: type: string description: Field-level validation errors (e.g. on 422 from POST /v1/worlds). schemaVersion: type: string required: - detail securitySchemes: SessionToken: type: http scheme: bearer bearerFormat: JWT description: >- The scoped runtime session JWT from POST /v1/sessions/token. The embed's browser presents it (Authorization: Bearer, or a `token` body field) to the runtime exchange routes. Not an API key. ````