Sign in vs a UNET client
The two products in one console and one package, what each is for, how their permissions, ids and tokens differ, and which SDK functions belong to which.
The console and the SDK serve two different products. They share the same sign-in underneath, which is why they look alike, but they have different purposes, permissions and rules.
The two products
Sign in with UNET lets a website or an app know who a person is. The person signs in on unet.social, your app gets an identity, and nothing else about UNET.
A UNET client is an app that acts as the person inside UNET: it reads their feed, posts for them, follows, likes, and so on. It is another way to use UNET, like the UNET apps themselves.
| Sign in with UNET | A UNET client | |
|---|---|---|
| Purpose | Identity: "who is this?" | Acting inside UNET as the person |
| Permissions | openid, profile (and offline_access) | One per kind of action, from content:read to settings:write |
| What the person sees | The app wants to sign them in | The app wants to see and do specific things, listed |
The id (sub) | A different value on every site, by default | The UNET user id |
| Your server | Verifies the token it is sent | Has nothing to verify |
| Who checks tokens | Your server, using UNET | UNET, on every request |
| Typical apps | A shop, a forum, a game that offers "Sign in with UNET" | A third-party UNET app, a dashboard, a post scheduler |
The app types in the console
The console asks what you are building when you create an app.
| Type | Has a secret | Verified domain | Use it for |
|---|---|---|---|
| Website with a server | Yes, shown once | Yes: you prove you own the domain with a DNS record | A site whose server signs people in with any OpenID Connect library. It can verify tokens with verifyAccessToken. |
| Single-page site or mobile/desktop app | No | No | A browser app or a native app. It is a public app and PKCE protects the sign-in. This is what @unet/id-web uses. |
The SDK is for the second type. It never holds a client secret, so it cannot be used by a website app, which needs a library that runs on the server.
Which SDK functions belong to which
Sign in with UNET:
signIn,handleRedirectCallback,restore,getUser,refreshUser,isSignedIn,onSessionChange,signOutgetIdToken, and on your serververifyAccessTokenandverifyIdToken
A UNET client:
- everything under
unet.api: feed, posts, comments, profiles, search, notifications, library, safety, settings, the Fediverse, media and live updates hasScope,getGrantedScopes, andsignInwithprompt: "consent"when you add permissions
getAccessToken, signIn and the session functions serve both.
An app can be both
A single-page app can sign people in and also act for them. A UNET dashboard, for instance, signs in, then calls unet.api.* with the permissions it registered. Such an app has REST API permissions, so by default it gets the UNET user id as sub.
If that app also has its own server that needs to know who is calling, it sends the ID token (getIdToken()) and checks it with verifyIdToken. The REST API calls themselves still go straight to UNET with the person's token.
Rules of thumb
- Do you only need to know who someone is? Register with the default permissions and use the sign-in functions. You get a per-site id, which protects your users.
- Do you need to read or write inside UNET? Add exactly the permissions you use. See Permissions.
- Does your server need to trust the person's identity? Verify the token there. See Verify on your server. A client that only calls
unet.api.*does not need to. - Mixing them is fine, confusing them is not. A permission is not identity, and the id from a REST API call is not your per-site
sub.