Sign in with Metaloot

The Adapter

@metaloot/auth is the recommended integration. It owns the OAuth callback, signed game session, session endpoint, logout endpoint, and browser sign-in state so games do not implement OAuth themselves.

npm install @metaloot/auth@latest

Version 0.1.1 and newer keeps localhost development cookies simple, but sets HTTPS auth cookies as SameSite=None; Secure so Metaloot-hosted iframes can establish and read the game session.

Node or Express games can mount the auth routes before serving static files:

import express from "express";
import { metalootAuth } from "@metaloot/auth/node";

app.use(metalootAuth({
  clientId: process.env.METALOOT_CLIENT_ID,
  clientSecret: process.env.METALOOT_CLIENT_SECRET,
  sessionSecret: process.env.METALOOT_SESSION_SECRET,
  redirectUri: "https://your-game.com/auth/metaloot/callback",
}));
app.use("/vendor/@metaloot/auth", express.static("node_modules/@metaloot/auth/dist"));

Mount the browser control where the game should show sign-in:

<div id="metaloot-auth"></div>
<script type="module">
  import { mountMetalootAuth } from "/vendor/@metaloot/auth/browser.js";
  mountMetalootAuth("#metaloot-auth", { gameName: "Your Game" });
</script>

Everything below documents the raw OAuth 2.0 flow behind the adapter. Use it only when your stack cannot run @metaloot/auth — if you use the adapter, you are done and can skip this.

Authorization Request

Redirect the player from the game to Metaloot. Use a random state value and verify it in your callback.

https://metaloot.app/oauth/authorize?response_type=code&client_id=METALOOT_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-game.com%2Fauth%2Fmetaloot%2Fcallback&scope=profile%20email&state=RANDOM_STATE

Token Exchange

Exchange the authorization code from your backend only. Keep the client secret out of browser code.

curl -X POST https://metaloot.app/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=METALOOT_CLIENT_ID" \
  -d "client_secret=METALOOT_CLIENT_SECRET" \
  -d "code=CODE_FROM_CALLBACK" \
  -d "redirect_uri=https://your-game.com/auth/metaloot/callback"

Successful response:

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "profile email",
  "user": {
    "id": "user_...",
    "email": "player@example.com",
    "name": "Player Name",
    "image_url": "https://..."
  }
}

Load the Player

Use the access token to fetch the Metaloot player profile. The sub value is the stable Metaloot player ID for your game.

curl https://metaloot.app/api/oauth/userinfo \
  -H "Authorization: Bearer METALOOT_ACCESS_TOKEN"

Next.js Callback Example

import { cookies } from "next/headers";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const url = new URL(request.url);
  const code = url.searchParams.get("code");
  const state = url.searchParams.get("state");
  const cookieStore = await cookies();

  if (!code || state !== cookieStore.get("metaloot_oauth_state")?.value) {
    return NextResponse.json({ error: "Invalid Metaloot callback" }, { status: 400 });
  }

  const response = await fetch("https://metaloot.app/api/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      client_id: process.env.METALOOT_CLIENT_ID!,
      client_secret: process.env.METALOOT_CLIENT_SECRET!,
      code,
      redirect_uri: "https://your-game.com/auth/metaloot/callback",
    }),
  });

  const token = await response.json();
  if (!response.ok) {
    return NextResponse.json(token, { status: 400 });
  }

  cookieStore.set("metaloot_access_token", token.access_token, {
    httpOnly: true,
    secure: true,
    sameSite: "lax",
    path: "/",
    maxAge: token.expires_in,
  });

  return NextResponse.redirect(new URL("/", request.url));
}

Legacy: Hosted Widget

Before the adapter existed, games embedded a hosted sign-in widget and implemented the OAuth callback and session handling themselves. New integrations should use the adapter instead — only keep this if your game already has its own callback and session code.

<div id="metaloot-auth"></div>
<script src="https://metaloot.app/metaloot-auth.js"></script>
<script>
  MetalootAuth.mount("#metaloot-auth", {
    clientId: "YOUR_METALOOT_CLIENT_ID",
    redirectUri: "https://your-game.com/auth/metaloot/callback",
    gameName: "Your Game",
  });
</script>