Quickstart

Sign a person in with UNET and show who they are, in about five minutes, with a plain browser app. Every step ends with something you can check.

By the end you will have a "Sign in with UNET" button that sends the person to unet.social and back, and a page that shows their username. You need Node 20 or newer and a browser app served on localhost (these examples assume Vite on port 5173, but any dev server works).

Register an app.

In the console choose Apps, New app, Single-page site or mobile/desktop app. Name it, add the return URL http://localhost:5173/auth/callback, and keep the default permissions (Sign in, Public profile). Copy the App ID; it looks like unet_3f9a....

Check: the app page shows your App ID and the status Active.

Install the SDK.

bash

npm install @unet/id-web

bash

pnpm add @unet/id-web

bash

yarn add @unet/id-web

Create one client for the whole app. Put it in a module you import everywhere, for example src/unet.ts.

import { UnetId } from "@unet/id-web";

export const unet = new UnetId({
  clientId: "unet_xxx", // your App ID
  redirectUri: `${location.origin}/auth/callback`,
  scopes: ["openid", "profile", "offline_access"], // offline_access: stay signed in
});

Add the button. Clicking it redirects to unet.social.
```
document.querySelector("#sign-in")!.addEventListener("click", () => {
  void unet.signIn({ returnTo: "/" });
});
```
Check: clicking the button opens unet.social, where you sign in and see what your app asks for.

Finish the sign-in on the return page. Serve this on /auth/callback: the page the person comes back to.

import { AccessDenied } from "@unet/id-web";

try {
  const { user, returnTo } = await unet.handleRedirectCallback();
  console.log("Signed in as", user.username);
  location.replace(returnTo);
} catch (e) {
  if (e instanceof AccessDenied) {
    location.replace("/"); // the person pressed Deny
  } else {
    throw e;
  }
}

Check: after you approve, the browser comes back to your page and the console shows Signed in as <your username>.

Restore the session on every other page. Call it once at startup. It returns the user, or null when nobody is signed in.
```
const user = await unet.restore();
if (user) {
  document.querySelector("#who")!.textContent = `@${user.username}`;
}
```
Check: reload the page: you are still signed in.

Sign out.

await unet.signOut(); // revokes the tokens at UNET and clears them here

What you get back

unet.getUser() returns the profile of the person:

{
  "sub": "k3Zr…",
  "username": "alice",
  "displayName": "Alice",
  "avatarUrl": "https://api.unet.ovh/users/avatar/…",
  "accountCreatedAt": "2029-05-06T07:08:09.000Z"
}

If it does not work

You see	Probably
unet.social says the return URL is not allowed	The return URL in the console differs from `redirectUri` (port, path, trailing slash).
`StateMismatch` on the return page	The page was opened twice, or the sign-in started in another tab or browser profile. Start again.
`invalid_client`	The App ID is wrong, the app is turned off, or it belongs to the other server (test vs production).
`discovery_invalid`	`issuer` points at a server that does not describe itself correctly. Check the address.
Nothing happens on click	Open the console of the browser: `signIn()` needs an `https` page or `localhost`.

What next

The sign-in flow in detailOptions, cancelling, deep links.Sessions and storageWhere tokens live, refresh, several tabs.Verify on your serverNever trust the browser's word.Call the UNET APIRead the feed, post, follow, with permissions.Going to productionThe checklist before launch.