Skip to content
LogoLogo

Read users

A session holds the user of a sign-in: an ID and a verified email address.

Overview

Each session holds its user: an ID and a verified email address. The ID stays the same at every sign-in and in every app.

The demo signs a user in through Tempo ID's dialog, and shows the session's user.

Read the userDemo
pnpx gitpick tempoxyz/accounts/tree/main/examples/webSource

Walkthrough

The web example runs these steps in a React app.

Install the packages

Create the instance

The react plugin adds accounts.useSession.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  chain: 'testnet',
  plugins: [react()],
})

Sign the user in

dialog.signIn returns the session.

import { accounts } from './tempo.config.js'
 
export function SignIn() {
  async function signIn() {
    const session = await accounts.dialog.signIn() 
    console.log(session.user)
    // { email: 'user@example.com', id: 'user_01M76GM8JG5NG1TZVQF63YM2MS' }
  }
 
  return (
    <button onClick={() => void signIn()} type="button">
      Sign in with Tempo
    </button>
  )
}
PropertyValue
user.emailThe user's verified email address
user.idThe user's ID, user_ and a ULID. Each token's sub holds it

Key the app's data by user.id, not by email.

Render the user

accounts.useSession also returns a session restored on a later visit. Without React, accounts.session.get() returns it.

import { accounts } from './tempo.config.js'
 
async function signIn() {
  const session = await accounts.dialog.signIn()
  console.log(session.user)
}
 
export function App() {
  const { isPending, session } = accounts.useSession() 
 
  if (isPending) return <p>Checking the session…</p>
  if (!session)
    return (
      <button onClick={() => void signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  return <p>Signed in as {session.user.email}</p>
}

Identify the user to a server

A server reads the user only from a token that it verifies:

TokenSession propertyNamesLifetime
ID tokenidTokenThe ID and the email address, to the app10 hours
Access tokenaccessTokenThe ID, to an API5 minutes

The app's server verifies the ID token. An API verifies the access token, which accounts.session.fetch sends.

import { accounts } from './tempo.config.js'
 
export function Me() {
  return (
    <button
      onClick={async () => {
        const response = await accounts.session.fetch({
          url: 'https://api.example/me',
        })
        console.log(await response.json())
      }}
      type="button"
    >
      Ask the API who I am
    </button>
  )
}

Use cases

Each use case reads one property of the session, or the user of an access token with the tokens plugin.

Read the account of the access key

session.accessKey.account holds the Tempo Account that the session's access key acts for. It is present only if the instance names accessKey, since each sign-in then requests an access key.

import { accounts } from './tempo.config.js'
 
export function Account() {
  const { session } = accounts.useSession()
 
  return <p>Tempo Account {session?.accessKey?.account}</p> 
}

Read the selected Tempo Account

session.account holds the Tempo Account that Tempo ID selects for the app. A sign-in through a redirect, a dialog, or a device reads none, so accounts.account.get reads it, and saves it in the session.

import { accounts } from './tempo.config.js'
 
export function Account() {
  async function read() {
    const account = await accounts.account.get() 
    console.log(account?.address)
  }
 
  return (
    <button onClick={() => void read()} type="button">
      Read the Tempo Account
    </button>
  )
}

Read the signer of a challenge

session.address holds the Tempo Account that signed the challenge of a sign-in, such as of Sign-In With Ethereum. After a sign-in without a challenge, it is absent. A server trusts it only after it verifies the signature, as Sign challenges shows.

import { accounts } from './tempo.config.js'
 
export function SignIn() {
  async function signIn() {
    const session = await accounts.dialog.signIn({
      challenge: async (signal) => {
        const response = await fetch('/challenge', { method: 'POST', signal })
        return response.text()
      },
    })
    console.log(session.address) 
  }
 
  return (
    <button onClick={() => void signIn()} type="button">
      Sign in with Tempo
    </button>
  )
}

Read the user on an API

An access token holds no email address. An API reads the user with tokens.userInfo, from the token that tokens.verifyAccessToken returns, as Authenticate requests shows.

A refused access token throws Accounts.RequestError with the reason invalid_token.

server.ts
import { Accounts } from 'accounts'
import { tokens } from 'accounts/plugins'
import { Hono } from 'hono'
 
const accounts = Accounts.create({
  clientId: 'https://app.example',
  plugins: [tokens()],
})
 
const app = new Hono()
 
app.get('/me', async (c) => {
  const token = await accounts.tokens.verifyAccessToken(c.req.raw)
  if (!token) return c.json({ error: 'invalid_token' }, 401)
 
  const user = await accounts.tokens.userInfo({ accessToken: token }) 
  // { email: 'user@example.com', id: 'user_01M76GM8JG5NG1TZVQF63YM2MS' }
  return c.json(user)
})
 
export default app

Next steps