# Authentication
Issue a server-side session for a connected Tempo account. The wallet signs a [SIWE](https://eips.ethereum.org/EIPS/eip-4361) challenge during `wallet_connect`, and your server verifies it to authenticate follow-up requests.
The cookie is issued by **your origin**. The SDK calls your `verify` endpoint from the app so the browser attaches the `Set-Cookie` to your domain.
## Demo
By the end of this guide, you will be able to authenticate the connected account against your own server and read the session from any request.
Hit **GET /me** before signing in to confirm the endpoint returns `401`. Sign in, then fetch again to see the authenticated response.
}>
## Walkthrough
::::steps
### Install the SDK
Install `accounts` together with Wagmi, Viem, and a server framework. This guide uses [Hono](https://hono.dev) on Cloudflare Workers; the same handler shape works on Node.js, Bun, Deno, Express, and Next.js.
:::code-group
```bash [npm]
npm i accounts wagmi viem hono
```
```bash [pnpm]
pnpm i accounts wagmi viem hono
```
```bash [bun]
bun i accounts wagmi viem hono
```
:::
### Set up the Auth Handler
Create a [`Handler.auth`](/docs/server/handler.auth) instance on your server. It mounts three endpoints under `path`:
* `POST /auth/challenge` — issue a single-use SIWE challenge
* `POST /auth` — verify a signed challenge and issue a session
* `POST /auth/logout` — revoke a session
It also exposes a `getSession` helper for reading the session from other routes.
```ts twoslash [worker/index.ts]
// @noErrors
import { Handler, Kv } from 'accounts/server'
import { env } from 'cloudflare:workers'
// `Kv.durableObject(env.NONCE_DO)` gives the auth handler a linearizable
// store for one-time-consume SIWE challenge nonces and issued sessions
// across concurrent worker instances.
export const auth = Handler.auth({
path: '/auth',
store: Kv.durableObject(env.NONCE_DO),
})
```
:::tip\[Pick the right store for production]
The default `Kv.memory()` store is fine for development. Multi-instance deployments need a linearizable backend so a SIWE nonce can only be consumed once.
On Cloudflare, use [`Kv.durableObject`](/docs/server/kv.durableObject). Elsewhere, any [`Kv`](/docs/server/kv) implementation that supports atomic `take` works.
:::
### Mount the Handler
Wire the handler into your server, and expose any routes that should be authenticated by reading the session via `getSession`.
```ts twoslash [worker/index.ts]
// @noErrors
import { Handler, Kv } from 'accounts/server'
import { env } from 'cloudflare:workers'
import { Hono } from 'hono'
// Re-export the reference Durable Object class so wrangler can wire it up.
export const NonceStorage = Kv.NonceStorage
const auth = Handler.auth({
path: '/auth',
store: Kv.durableObject(env.NONCE_DO),
})
const app = new Hono()
// Forward every request under `/auth` to the auth handler so the SDK // [!code ++]
// can hit `/auth/challenge`, `/auth`, and `/auth/logout`. // [!code ++]
app.all('/auth', (c) => auth.fetch(c.req.raw)) // [!code ++]
app.all('/auth/*', (c) => auth.fetch(c.req.raw)) // [!code ++]
// Reads the SIWE-issued session and returns the connected address. // [!code ++]
// Demonstrates how an authenticated endpoint consumes Handler.auth. // [!code ++]
app.get('/me', async (c) => { // [!code ++]
const session = await auth.getSession(c.req.raw) // [!code ++]
if (!session) return c.json({ error: 'unauthenticated' }, 401) // [!code ++]
return c.json({ address: session.address, chainId: session.chainId }) // [!code ++]
}) // [!code ++]
export default app
```
:::tip\[Using a different framework?]
`Handler.auth` exposes both `fetch` (Web Fetch API) and `listener` (Node.js `RequestListener`) entrypoints, so you can plug it into any server framework:
```ts
createServer(auth.listener) // Node.js
Bun.serve({ fetch: auth.fetch }) // Bun
Deno.serve({ fetch: auth.fetch }) // Deno
app.all('*', c => auth.fetch(c.request)) // Elysia
app.use(auth.listener) // Express
app.use(c => auth.fetch(c.req.raw)) // Hono
export const GET = auth.fetch // Next.js
export const POST = auth.fetch // Next.js
```
:::
### Configure the Connector
Pass the auth endpoint to the connector via the `auth` capability. The SDK runs the SIWE round-trip inside `wallet_connect`, sharing the same passkey ceremony.
```tsx twoslash [src/config.ts]
// @noErrors
import { createConfig, http } from 'wagmi'
import { tempo, tempoModerato } from 'wagmi/chains'
import { tempoWallet } from 'wagmi/connectors'
export const config = createConfig({
chains: [tempoModerato, tempo],
connectors: [tempoWallet({ auth: '/auth' })], // [!code ++]
multiInjectedProviderDiscovery: false,
transports: {
[tempo.id]: http(),
[tempoModerato.id]: http(),
},
})
```
:::tip\[Object form]
Use the [object form](/docs/rpc/wallet_connect) to override individual endpoints, opt into a `{ token }` body via `returnToken`, or split challenge/verify across hosts.
```ts
tempoWallet({
auth: {
challenge: 'https://auth.example.com/challenge',
verify: 'https://auth.example.com/verify',
logout: 'https://auth.example.com/logout',
returnToken: true,
},
})
```
:::
### Display the Sign-In Button
Drop in a connect button — no auth-specific code required. The Wagmi `connect` mutation triggers `wallet_connect`, and the auth round-trip happens inside that call.
```tsx twoslash [src/App.tsx]
// @noErrors
import { useConnect, useConnection, useConnectors, useDisconnect } from 'wagmi'
function Connect() {
const { address } = useConnection()
const { mutate: connect, isPending } = useConnect()
const { mutate: disconnect } = useDisconnect()
const [connector] = useConnectors()
if (address)
return (
)
return (
)
}
```
### Call authenticated resource
With the session cookie attached to your origin, any authenticated route just works. Use `credentials: 'include'` so the cookie is sent on the fetch.
```tsx twoslash [src/App.tsx]
// @noErrors
import { useState } from 'react'
function Me() {
const [me, setMe] = useState(null)
async function fetchMe() {
const res = await fetch('/me', { credentials: 'include' }) // [!code focus]
setMe(await res.json())
}
return (
{JSON.stringify(me, null, 2)}
)
}
```
### Sign Out
You don't need to call `/auth/logout` yourself: `wallet_disconnect` automatically POSTs to the configured `logout` endpoint, which clears the session cookie. The next `GET /me` returns `401`.
```tsx twoslash
// @noErrors
import { useDisconnect } from 'wagmi'
const { mutate: disconnect } = useDisconnect()
// Clears the wallet connection AND the server session cookie.
disconnect()
```
### Deploy to Production
When you're ready to go live, follow the [Deploying to Production](/docs/production) guide. Then pin a canonical [`origin`](/docs/server/handler.auth#origin) on `Handler.auth` to prevent a spoofed `x-forwarded-host` from shifting the SIWE domain.
```ts twoslash
// @noErrors
import { Handler, Kv } from 'accounts/server'
const auth = Handler.auth({
origin: 'https://app.example.com', // [!code ++]
path: '/auth',
store: Kv.durableObject(env.NONCE_DO),
})
```
::::
## Recipes
### Request a Verified Email
Alongside the authentication session, you can request the account's verified email via the `identity` capability.
Set `withCapabilities: true` so the connect result includes per-account `capabilities`, then read the email from the authenticated account.
```tsx twoslash [src/App.tsx]
// @noErrors
import { useConnect, useConnectors } from 'wagmi'
function Connect() {
const { connectAsync } = useConnect()
const [connector] = useConnectors()
return (
)
}
```
:::warn
The plain `email` string is fine for client-side display, but anyone can set it. The result also carries a signed `idToken` that your server can verify to trust the email. See [Verify the Email Server-Side](#verify-the-email-server-side).
:::
#### Verify the Email Server-Side
Alongside the plain `email`, the wallet returns a signed token proving the email belongs to the account. Your auth handler checks the signature and adds the verified email to the session automatically — set [`identity`](/docs/server/handler.auth#identity) only to require an email or use your own wallet.
```ts twoslash [worker/index.ts]
// @noErrors
import { Handler, Kv } from 'accounts/server'
import { env } from 'cloudflare:workers'
const auth = Handler.auth({
path: '/auth',
store: Kv.durableObject(env.NONCE_DO),
})
// In an authenticated route, the verified email is on the session. // [!code focus]
app.get('/me', async (c) => { // [!code focus]
const session = await auth.getSession(c.req.raw) // [!code focus]
if (!session) return c.json({ error: 'unauthenticated' }, 401)
return c.json({ address: session.address, email: session.email }) // [!code focus]
})
```
## Notes & Gotchas
### Cookies are issued by your origin
The session cookie is set on **your app's** origin, not the wallet's. The SDK sees `Set-Cookie` because it makes the verify call itself.
This means `/auth` and `/me` must live on the same origin as your app for the cookie to attach.
### Same-origin in development
Browsers attach `SameSite=Lax` cookies only on same-site requests. Run your auth handler on the app's origin — Vite's proxy or a colocated worker (see [`authentication`](https://github.com/tempoxyz/accounts/tree/main/examples/authentication)) is the easiest path.
### Non-browser clients
Use the object form with `returnToken: true` when the SDK can't store cookies (CLI, React Native). The verify response then returns `{ token }` for use as `Authorization: Bearer `.
```ts
tempoWallet({ auth: { url: '/auth', returnToken: true } })
```
### Custom verification logic
Pass [`onAuthenticate`](/docs/server/handler.auth#onauthenticate) to gate session issuance. Throw to reject the request with a `401`, or return a `Response` to merge custom JSON onto the verify reply.
## Next Steps