Skip to content
LogoLogo

Authorize access keys

Name what an access key may spend and when it expires, and request it at sign-in or later.

Overview

An access key signs for the user's Tempo Account within the limits and the expiry that the user approves on Tempo ID's approval page. An app requests it at sign-in, or later for a signed-in user, such as at the first payment. The session then holds the access key.

RequestCallTempo ID shows
At sign-indialog.signIn, with the instance's accessKeyThe sign-in and the approval page
After sign-indialog.signIn, with the call's accessKeyOnly the approval page
After sign-in, in a first-party appaccounts.authorizeNo page

The demo signs a user in with an access key of the selected limit and expiry, then authorizes a new access key for the signed-in user.

Authorize an access keyDemo
pnpx gitpick tempoxyz/accounts/tree/main/examples/webSource

Walkthrough

The web example runs these steps in a React app.

Name the permissions

The accessKey option of Accounts.create returns each sign-in's permissions. A duration counts from the sign-in, and a limit is in the token's units.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  accessKey: () => ({
    expiry: '1d',
    limits: [{ limit: '100', token: 'ousd' }],
  }),
  chain: 'testnet',
  plugins: [react()],
})
PropertyValue
expiryA duration, or Unix seconds. Absent, Tempo ID fills its default expiry
limitsThe amount of each token that the access key may spend, in total or for each period
scopesThe calls that the access key may make. Absent, the package fills transfers of each token of the limits

Tempo ID refuses an access key without bounds, such as one without limits.

Request the access key at sign-in

Call dialog.signIn in a click handler, since a popup opens only within a user gesture. If the user approves the limits and the expiry on Tempo ID's approval page, the call returns the session.

import { accounts } from './tempo.config.js'
 
export function SignIn() {
  return (
    <button onClick={() => accounts.dialog.signIn()} type="button">
      Sign in with Tempo
    </button>
  )
}

If the user denies the access key, the call rejects with Accounts.RequestError, whose code is access_denied.

Read the access key

Permissions.fromAccessKey returns the key authorization's limits and scopes, with each limit in base units.

import { Permissions } from 'accounts'
import { formatUnits } from 'viem'
import { accounts } from './tempo.config.js'
 
export function App() {
  const { session } = accounts.useSession()
 
  if (!session?.accessKey)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  const { account, keyAuthorization } = session.accessKey
  const { limits } = Permissions.fromAccessKey(session.accessKey) 
  // The expiry is in Unix seconds.
  const expiry = new Date(Number(keyAuthorization.expiry) * 1000)
 
  return (
    <ul>
      <li>Tempo Account {account}</li>
      <li>Access key {keyAuthorization.keyId}</li>
      <li>Expires {expiry.toLocaleString()}</li>
      {limits?.map((entry) => (
        <li key={entry.token}>
          Sends up to {formatUnits(BigInt(entry.limit), 6)} of {entry.token}
        </li>
      ))}
    </ul>
  )
}

Use cases

Each use case sets one property of the Permissions that accessKey returns, or requests the access key with another call.

Authorize an access key after sign-in

An app can sign a user in without an access key, and request one at the first payment. An instance with accessKey set to false requests none at sign-in. Without it, each sign-in requests an access key that may transfer up to 5 OUSD for a day. For one sign-in without an access key, pass false as the sign-in's accessKey.

A second button calls dialog.signIn with accessKey, which overrides the instance's. The user holds a Tempo ID session, so the dialog opens on the approval page only, and the returned session replaces the instance's session.

import { Permissions } from 'accounts'
import { accounts } from './tempo.config.js'
 
// Sends up to 10 OUSD each day, for 30 days.
const daily = Permissions.from({
  expiry: '30d',
  limits: [{ limit: '10', period: '1d', token: 'ousd' }],
})
 
export function App() {
  const { session } = accounts.useSession()
 
  if (!session)
    return (
      <button onClick={() => accounts.dialog.signIn()} type="button">
        Sign in with Tempo
      </button>
    )
 
  if (!session.accessKey)
    return (
      <button
        onClick={() => accounts.dialog.signIn({ accessKey: daily })}
        type="button"
      >
        Authorize payments
      </button>
    )
 
  return <p>Tempo Account {session.accessKey.account}</p>
}

Authorize with no page in a first-party app

accounts.authorize requests an access key for the browser's Tempo ID session, and shows no page. The access key must fit the headless ceiling, unless the app holds the tempo-id:sign scope. A third-party app receives the reason rejected, so the handler falls back to the dialog.

import { Accounts, Permissions } from 'accounts'
import { accounts } from './tempo.config.js'
 
const permissions = Permissions.from({
  expiry: '1d',
  limits: [{ limit: '10', token: 'ousd' }],
})
 
export function Authorize() {
  async function authorize() {
    try {
      await accounts.authorize({ accessKey: permissions }) 
    } catch (error) {
      if (
        !(error instanceof Accounts.RequestError) ||
        error.reason !== 'rejected'
      )
        throw error
      await accounts.dialog.signIn({ accessKey: permissions })
    }
  }
 
  return (
    <button onClick={authorize} type="button">
      Authorize payments
    </button>
  )
}

Without a Tempo ID session, the call returns undefined, and empties the instance's session.

Sign with a passkey on the page

If a passkey owns the Tempo Account, accounts.authorize rejects with the reason webauthn_required. With passkey set to true, the passkey's ceremony runs on the page, so the call needs a click.

import { Permissions } from 'accounts'
import { accounts } from './tempo.config.js'
 
const permissions = Permissions.from({
  expiry: '1d',
  limits: [{ limit: '10', token: 'ousd' }],
})
 
export function Authorize() {
  return (
    <button
      onClick={() =>
        accounts.authorize({ accessKey: permissions, passkey: true }) 
      }
      type="button"
    >
      Authorize payments
    </button>
  )
}

Reset a limit each period

period resets a limit after each period, such as each day. Without it, the limit is a total for the life of the access key.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  accessKey: () => ({
    expiry: '30d',
    limits: [{ limit: '10', period: '1d', token: 'ousd' }], 
  }),
  chain: 'testnet',
  plugins: [react()],
})

Approve a spender

spenders names the contracts that the access key may approve to spend the token. Without it, the filled scopes hold no approval.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
 
export const accounts = Accounts.create({
  accessKey: () => ({
    expiry: '1d',
    limits: [
      {
        limit: '100',
        spenders: ['0x000000000000000000000000000000000000bEEF'], 
        token: 'ousd',
      },
    ],
  }),
  chain: 'testnet',
  plugins: [react()],
})

Name the scopes

Named scopes, built with Viem's Scopes, replace the filled ones. This access key sends OUSD to one recipient only.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
import { Addresses, Scopes } from 'viem/tempo'
 
export const accounts = Accounts.create({
  accessKey: () => ({
    expiry: '1d',
    limits: [{ limit: '100', token: 'ousd' }],
    scopes: [
      Scopes.tip20(Addresses.ousd).transfer({
        recipients: ['0x000000000000000000000000000000000000dEaD'],
      }),
    ],
  }),
  chain: 'testnet',
  plugins: [react()],
})

Pay fees without a stablecoin limit

Tempo charges an access key's fees to its limit of the fee token, so limits without a stablecoin, such as MACH alone, pay no fee. For such limits with named scopes, the package adds a fee allowance: 0.1 of each fee stablecoin on the chain, which no scope can send.

tempo.config.ts
import { Accounts } from 'accounts'
import { react } from 'accounts/react'
import { Scopes } from 'viem/tempo'
 
const mach = '0x20c000000000000000000000f37de3740adec032'
 
export const accounts = Accounts.create({
  accessKey: () => ({
    expiry: '1d',
    limits: [{ limit: '2', token: 'mach' }], 
    scopes: [Scopes.tip20(mach).transferWithMemo()], 
  }),
  chain: 'testnet',
  plugins: [react()],
})

Filled scopes receive no allowance, since they call the payment channel reserve, which could spend it. Without named scopes, add a stablecoin limit that holds the fees.

Next steps