Skip to main content
Alakazam is the programmable worlds API. This guide takes you from zero to an embedded, playable world — create one, then program it into your product.

​
Get an API key

1

Sign in to the dashboard

Open the developer dashboard and sign in with your Alakazam account.
2

Create an app

An app is your project. Every world, session, and usage record is attributed to it. Create one and give it a name.
3

Mint a secret key

From your app, generate a secret key (sk_test_…). It’s shown once — copy it now and store it securely.
Save your API key in a secure location and never share it. Secret keys (sk_…) belong on your server only — never in a browser, a prompt, a log, or version control.

​
Create your first world

To verify your setup, we recommend creating a world from only a text premise. Send a POST to /v1/worlds with your secret key: 
curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -d '{
    "name": "Mystical Forest",
    "premise": "A mystical forest with glowing mushrooms"
  }'
The response contains your new world’s id, a shareable slug, and its cover image: 
{
  "worldId": "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
  "slug": "mystical-forest",
  "ok": true,
  "cover": "https://cdn.alakazam.gg/covers/mystical-forest.png",
  "schemaVersion": "1.0"
}
Creation reserves one generation against your daily quota. You can check what’s left any time with GET /v1/usage.

​
Embed it

A world is meant to be played. Embedding is two steps: mint a session token on your server, then boot the world in the browser with the SDK.
1

Mint a session token (server)

Call /v1/sessions/token with your secret key. Bind it to the player and to the origin you’ll embed on.
const r = await fetch("https://api.alakazam.gg/v1/sessions/token", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    worldId: "dc2c65e4-68d3-4210-a01e-7a54cc9ded2a",
    playerIdentity: user.id,
    origin: "https://yourgame.com",
  }),
});
const { token } = await r.json(); // send `token` to the browser
2

Boot the world (browser)

Install the SDK and mount the world. Pass the session token — never your secret key.
npm install @alakazamworld/embed

import { createEmbed } from "@alakazamworld/embed";

createEmbed({
  container: "#game",
  slug: "mystical-forest",
  token, // the session token from your server
  onEnding: (e) => console.log("ending reached", e),
});

​
Next steps

World generation examples

Create from a premise, an image URL, or an uploaded frame.

Embedding

Theming, events, token refresh, and cross-origin security.