SizWalletSizWallet

The actual way

Integrate auth on your site

Five steps. Do them in this order. The user must see wallet.siz.land in the address bar when they approve — never an iframe of our authorize page.

1. Get a registered client

Logging into a SizWallet does not mint keys. Send the request on Get keys. We register your exact redirect URIs. Unregistered redirects never bounce to your domain.

2. Read discovery (optional)

Libraries that support OIDC can load this once. You can also hard-code the endpoints below — that is what we do in the NextAuth example.

Discovery

https://wallet.siz.land/.well-known/openid-configuration

3. Create PKCE, then send the user here

S256 only. Generate a verifier (43–128 unreserved characters), store it in your session, send the SHA-256 challenge on the authorize URL.

PKCE on your server

import { createHash, randomBytes } from "crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
// Send challenge on /oauth/authorize. Keep verifier on your server for the token call.

Authorize URL

https://wallet.siz.land/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fyour-site.example%2Fcallback&response_type=code&scope=openid&state=RANDOM_STATE&nonce=RANDOM_NONCE&code_challenge=S256_CHALLENGE&code_challenge_method=S256

4. Exchange the code on your server

The browser lands on your redirect_uri with code and state. Check state. Then POST the code from your backend — never from a public frontend if you have a confidential client.

Token request

POST https://wallet.siz.land/api/wallet/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "THE_CODE_FROM_REDIRECT",
  "redirect_uri": "https://your-site.example/callback",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code_verifier": "THE_PKCE_VERIFIER"
}

5. Verify the id_token, store sub

Fetch JWKS, verify RS256, iss = https://wallet.siz.land, aud = your client_id, nonce matches, exp is in the future. Persist sub as that user’s id on your site. If sub contains did:key, reject the login — that would be a bug, not a feature.

JWKS

https://wallet.siz.land/api/wallet/oauth/jwks

NextAuth (App Router)

Same shape as our internal auth example. Secrets stay in environment variables. The user still leaves your origin and signs on wallet.siz.land.

auth.ts

import type { NextAuthOptions } from "next-auth";

const issuer = "https://wallet.siz.land";

export const authOptions: NextAuthOptions = {
  providers: [
    {
      id: "sizwallet",
      name: "SizWallet",
      type: "oauth",
      issuer,
      authorization: {
        url: `${issuer}/oauth/authorize`,
        params: { scope: "openid" },
      },
      token: `${issuer}/api/wallet/oauth/token`,
      userinfo: `${issuer}/api/wallet/oauth/userinfo`,
      jwks_endpoint: `${issuer}/api/wallet/oauth/jwks`,
      clientId: process.env.SIZWALLET_CLIENT_ID,
      clientSecret: process.env.SIZWALLET_CLIENT_SECRET,
      idToken: true,
      checks: ["pkce", "state", "nonce"],
      client: { token_endpoint_auth_method: "client_secret_post" },
      profile(profile) {
        return { id: profile.sub, name: null, email: null, image: null };
      },
    },
  ],
};
User lands on wallet.siz.land /oauth/authorize, not an iframe.
PKCE S256 on every authorize + token pair.
client_secret never in a mobile app, git repo, or browser bundle.
Redirect URI matches the registry character-for-character.
You treat pw:… as the account id. You do not ask for a seed phrase.
You do not call wallet API routes with our operator X-API-Key from the browser.