Express
Guia completo de autenticação com Clowk no Express: clowkMiddleware, requireAuth para rotas protegidas, o JWT em req.auth e a extração do token.
Instalação
pnpm add @clowk/express @clowk/coreConfiguração
import express from 'express'
import { clowkMiddleware, requireAuth } from '@clowk/express'
const app = express()Proteger todas as rotas
Aplique clowkMiddleware de forma global para decodificar o JWT em toda requisição. O payload decodificado fica em req.auth:
app.use(clowkMiddleware({
secretKey: process.env.CLOWK_SECRET_KEY,
}))
app.get('/dashboard', (req, res) => {
res.json({ user: req.auth })
})Opções do middleware
| Opção | Tipo | Descrição |
|---|---|---|
secretKey | string | Secret key para verificar o JWT |
tokenParam | string | Nome do parâmetro de query (padrão: "token") |
cookieKey | string | Nome do cookie (padrão: "clowk_token") |
Proteger rotas específicas
Use requireAuth() para proteger rotas individuais. Ele retorna 401 se não encontrar um token válido:
app.get('/public', (req, res) => {
res.json({ message: 'This is public' })
})
app.get('/dashboard', requireAuth(), (req, res) => {
res.json({ user: req.auth })
})Tipo de req.auth
Quando há um token válido, req.auth contém o payload decodificado do JWT:
interface JwtPayload {
iss?: string // "clowk"
sub?: string // UUID do usuário
email?: string // "[email protected]"
name?: string // "Jane Doe"
avatar_url?: string
provider?: string // "google" | "github" | "twitter" | "email"
instance_id?: string
app_id?: string
iat?: number
exp?: number
}Com clowkMiddleware, req.auth é null se nenhum token for encontrado (soft auth). Com requireAuth, a requisição é recusada com 401 antes de chegar ao seu handler.
Extração do token
O middleware extrai o JWT de (nesta ordem):
- Query parameter —
?token=eyJ... - Header Authorization —
Bearer eyJ... - Cookie —
clowk_token
Exemplo completo
import express from 'express'
import { clowkMiddleware, requireAuth } from '@clowk/express'
const app = express()
app.use(clowkMiddleware({
secretKey: process.env.CLOWK_SECRET_KEY,
}))
app.get('/', (req, res) => {
res.json({ authenticated: !!req.auth })
})
app.get('/profile', requireAuth(), (req, res) => {
res.json({
id: req.auth?.sub,
email: req.auth?.email,
name: req.auth?.name,
})
})
app.listen(3000)Next.js
Guia completo de autenticação com Clowk no Next.js: middleware para proteger rotas, auth() em Server Components e Route Handlers, e hooks React no cliente.
Hono
Guia completo de autenticação com Clowk no Hono: clowkMiddleware, requireAuth, o contexto auth e deploy em Cloudflare Workers, Bun, Deno e Node.js.