DEVELOPER & AI AGENT DOCUMENTATION

Build Open Worlds & Pod Apps in Minutes

Authenticate players with zero API keys via static Solid-OIDC JSON-LD, read/write portable 3D avatars across 5 official SDKs, connect coding agents via MCP, or self-host the single binary.

02 · OFFICIAL CLIENT SDKS

5-Language SDK Quickstarts

Every official SDK handles RFC 9449 ES256 DPoP proof signing, WebID storage discovery, and ETag optimistic concurrency out of the box.

pnpm add @wolin-id/client @wolin-id/react
import { WolinProvider, usePodResource, useWolinSession } from '@wolin-id/react';

export const App = () => (
  <WolinProvider
    clientId={`${location.origin}/client-id.jsonld`}
    redirectUri={`${location.origin}/auth/callback`}
    defaultOidcIssuer="https://auth.wolin.id"
  >
    <WorldHud />
  </WolinProvider>
);

function WorldHud() {
  const { isAuthenticated, session, login } = useWolinSession();
  const { save } = usePodResource(isAuthenticated ? '/private/world-save.ttl' : null);
  return isAuthenticated
    ? <button onClick={() => void save('<#save> <https://wolin.id/ns#score> 42 .')}>Save ({session?.webId})</button>
    : <button onClick={() => void login()}>Continue with Wolin</button>;
}

Zero-Review Client ID (public/client-id.jsonld)

No developer portal API keys required. Serve this static JSON-LD file from the same origin as your redirect_uri.

{
  "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",
  "client_id": "https://world.example.com/client-id.jsonld",
  "client_name": "My Wolin 3D World",
  "redirect_uris": ["https://world.example.com/auth/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "openid webid offline_access"
}

Cross-World Vocabulary (https://wolin.id/ns#)

Use these canonical predicates so 3D avatars, wearables, and portals work across every Wolin world.

wolin:displayName Cross-world 3D nametag & Passport display name (xsd:string)
wolin:avatarGlbUrl Portable glTF 2.0 (.glb) avatar URL for Three.js, R3F & Unity
wolin:avatarVrmUrl Humanoid VRM (.vrm) avatar URL with blendshapes for VTuber stages
wolin:worldLinks · wolin:wearableItem Passport portal directory links and equipped 3D wearable items
03 · SOVEREIGN POD ARCHITECTURE

Control Plane, Data Plane & Protocol Guardrails

Wolin separates global edge authentication from origin-isolated user Pods, giving every handle its own isolated graph store and zero-egress R2 asset delivery.

IDENTITY & CONTROL PLANE

https://auth.wolin.id

  • Passwordless Solid-OIDC Provider with PKCE (S256) and sender-constrained DPoP (ES256) tokens.
  • 6 social OAuth providers (Google, Apple, Kakao, Naver, Discord, GitHub) + Email Magic Link with verified-email linking.
  • Live handle availability API (GET /api/handles/check?handle=...) with ~180 reserved system handles and anti-hijack tombstones.
SOVEREIGN POD DATA PLANE

https://{handle}.wolin.id

  • W3C Solid 0.11 Linked Data Platform (LDP) with per-Pod database isolation and WAC / ACP consent evaluation.
  • Content negotiation on / and /profile/card: browsers render HTML Digital Passport; apps requesting Accept: text/turtle receive RDF.
  • Short-lived HMAC-SHA256 signed 302 redirects stream large .glb/.vrm binaries directly from Cloudflare R2 ($0 egress).

Rule 01 · DPoP ath Binding

Send Authorization: DPoP <token> with a fresh DPoP proof containing unpadded Base64URL SHA-256 ath and query-stripped htu.

Rule 02 · LDP Trailing Slash

Containers must end with / (e.g. /private/saves/); RDF documents and binary files must not end with / (e.g. /private/saves/slot1.ttl).

Rule 03 · ETag Concurrency

Pass If-Match: <etag> on updates and If-None-Match: * on first init; catch 412 Precondition Failed and merge cleanly.

04 · SELF-HOSTING & ZERO LOCK-IN EXIT

Run Your Own Pod Server or Export Anytime

Start on Wolin Cloud’s $0 Free Tier (1 GB) or run the open-core wolin-server single binary on your laptop, Docker host, or home server with lossless .tar.zst migration.

Local Ephemeral Sandbox (--in-memory)

Boot a clean local Solid 0.11 + MCP Pod server on port 4000 in milliseconds for integration tests.

# Option A: From open-core source (github.com/wolin-id/wolin)
cargo run --release -p wolin-server -- --in-memory

# Option B: Docker home server with persistent volume
docker run -d --name wolin-pod \
  -p 4000:4000 \
  -e WOLIN_BASE_URL="https://pod.yourdomain.com" \
  -v wolin-data:/var/lib/wolin \
  ghcr.io/wolin-id/wolin:latest

Lossless Pod Bundle Migration (.tar.zst)

Export your semantic graph, binary assets, and access rules together — rewriting internal URIs cleanly when moving domains.

# Export full Pod (RDF quads + blobs + .acl policies)
wolin export --pod alice --output ./alice-pod-backup.tar.zst

# Import onto your self-hosted server with URI relocation
wolin import --bundle ./alice-pod-backup.tar.zst \
  --base-url "https://pod.yourdomain.com"