Build with Renown

How Renown login works

1. 1

   Your app sends the user to a connect link

   The link names your app by its DID and says where to send the user afterwards.

2. 2

   The user approves

   They sign in with their wallet and sign one credential that authorises your app key.

3. 3

   Renown stores the credential

   It is public and revocable. The user is sent back with their DID in ?user=.

4. 4

   Your app verifies

   Your server checks each request’s token and the credential behind it with @renown/sdk.

Connect link reference

A connect link opens the Renown sign-in flow for your app:

https://www.renown.id/?connect=<app DID>&returnUrl=<url>&expiresInDays=<n>

Build a connect link

Fill in your app's details. The link is checked with the same rules the sign-in flow applies.

SDK quick start

@renown/sdk gives your app a key pair and identity in the browser, logs the user in once they approve, signs short-lived bearer tokens, and verifies them on your server.

pnpm add @renown/sdk

1. Give your app an identity

import { RenownBuilder } from '@renown/sdk'

// Creates (once) and stores your app's key pair in the browser.
const renown = await new RenownBuilder('my-app').build()

// Your app's identity: pass it as ?connect= in the connect link.
const connectUrl = `https://www.renown.id/?connect=${renown.did}&returnUrl=${encodeURIComponent(location.href)}`

2. Complete the login when the user returns

// Back from Renown: ?user=did:pkh:eip155:<chainId>:<address>
const user = new URL(location.href).searchParams.get('user')
if (user) {
  // Loads the credential the user just signed for renown.did.
  await renown.login(decodeURIComponent(user))
}

3. Call your API with a bearer token

// A short-lived token signed by your app key, for your own API.
const token = await renown.getBearerToken({ expiresIn: 600 })
await fetch('/api/notes', { headers: { Authorization: `Bearer ${token}` } })

4. Verify requests on your server

import { verifyAuthBearerToken, fetchDelegationCredential } from '@renown/sdk'

export async function authenticate(token: string) {
  // 1. The token is well-formed, unexpired and signed by its issuer (your app key).
  const jwt = await verifyAuthBearerToken(token)
  if (!jwt) return null
  // 2. The wallet in the token really authorised that key: an unrevoked,
  //    unexpired credential exists on Renown.
  const { address, chainId } = jwt.verifiableCredential.credentialSubject
  const grant = await fetchDelegationCredential({ address, chainId, appDid: jwt.issuer })
  return grant ? { address, chainId } : null
}

App identity and stats

Apps built and hosted on Vetra get their Renown identity there, along with a public app profile at renown.id/app/<DID>. Apps can report per-user stats that appear on user profiles and app pages; see the app stats docs.

Sign in with Renown (OIDC)

Renown is also an OpenID Connect provider (authorization code flow with PKCE, RS256 ID tokens). Registered OIDC clients use the issuer below:

https://switchboard.renown.vetra.io/api/@powerhousedao/renown-package/oidc

curl https://switchboard.renown.vetra.io/api/@powerhousedao/renown-package/oidc/.well-known/openid-configuration

Client registration is not self-service yet: clients are registered by the Renown operators.

Public GraphQL reads

Profiles, app profiles and app stats are public. Read app profiles and stats from https://switchboard.renown.vetra.io/graphql/renown-stats (queries appProfile, appProfiles, appStats, userStats) and user profiles from https://switchboard.renown.vetra.io/graphql (renownUsers).

query {
  appProfiles(limit: 5) {
    items { appDid name tagline category }
    next
  }
}

curl -s https://switchboard.renown.vetra.io/graphql/renown-stats \
  -H 'content-type: application/json' \
  -d '{"query":"{ appProfiles(limit: 5) { items { appDid name } next } }"}'