Add dots.id to any app.

quickstart

From zero to signed-in

1. 1

   Get an API key

   Your API key is a dots OAuth client id. Create one in the developer portal at /dev/clients → New client. For a browser/SPA app choose public (PKCE — no secret) and add your redirect URI, e.g. http://localhost:3000/dots/callback.

2. 2

   Install the SDK

   One package, alpha-tagged. Pin an exact version while the API evolves.

   npm i @wrldbld/dots@alpha
   # or: bun add @wrldbld/dots@alpha

3. 3

   Set the env

   The key is your public OAuth client id — safe in client code (public clients use PKCE, no secret).

   # .env.local
   NEXT_PUBLIC_DOTS_API_KEY="client_..."        # your dots app's public OAuth client id (safe in the browser)
   # NEXT_PUBLIC_DOTS_ISSUER="https://dots.localhost"   # point at a dev issuer while testing; omit in prod

4. 4

   Create the client

   A single framework-agnostic factory. Works in Next, Vite, Svelte, anywhere.

   // lib/dots.ts
   import { createDots } from "@wrldbld/dots";
   
   export const dots = createDots({
     apiKey: process.env.NEXT_PUBLIC_DOTS_API_KEY!,
     // issuer defaults to https://www.dots.id; redirectUri defaults to `${origin}/dots/callback`
   });

5. 5

   Sign in with dots

   Redirects to dots.id for branded consent, then back to your callback.

   // a sign-in button — kicks off OAuth 2.1 + PKCE, branded consent at dots.id
   import { dots } from "@/lib/dots";
   
   export function SignIn() {
     return <button onClick={() => dots.signIn({ returnTo: "/app" })}>Sign in with dots</button>;
   }

6. 6

   Handle the callback

   Add a /dots/callback route that completes the PKCE exchange.

   // app/dots/callback/page.tsx
   "use client";
   import { useEffect } from "react";
   import { dots } from "@/lib/dots";
   
   export default function Callback() {
     useEffect(() => {
       dots.handleCallback().then(() => (location.href = "/app"));
     }, []);
     return <p>Signing you in…</p>;
   }

7. 7

   Read the user

   Identity comes straight from the access-token claims — no extra round-trip.

   const user = await dots.getUser();
   // { sub, username, walletAddress, dotsIdStatus, email }
   const token = await dots.getAccessToken();   // send as Bearer to your backend
   await dots.signOut();

8. 8

   Verify tokens on your server

   Trust the user on your own backend by verifying the token via @wrldbld/dots/server — zero-dependency (Web Crypto + fetch), runs in Node, Bun, Deno, and edge. Stateless: for revocation-sensitive checks use introspectDotsToken().

   // app/api/whatever/route.ts — protect YOUR backend with the dots token
   import { verifyDotsToken, getBearerToken, hasScope } from "@wrldbld/dots/server";
   
   export async function GET(request: Request) {
     const token = getBearerToken(request);
     try {
       const claims = await verifyDotsToken(token); // RS256, verified against dots JWKS
       if (!hasScope(claims, "data:read")) return new Response("forbidden", { status: 403 });
       return Response.json({ sub: claims.sub, wallet: claims.walletAddress });
     } catch {
       return new Response("unauthorized", { status: 401 });
     }
   }

sdk

Client surface

server

Server surface — @wrldbld/dots/server

Verify dots tokens on your own backend. Zero dependencies; works in any runtime.

scopes

OAuth scopes

reference

More

• · Install walkthrough — the marketing-flavored version of this page.
• · Package source & README — full API reference, types, and changelog.
• · Developer dashboard — create/manage OAuth clients (API keys).
• · OIDC discovery — issuer metadata, endpoints, JWKS.