Skip to main content

Vengtoo + Express

Add authorization to your Express API in 5 minutes.

Install​

npm install @vengtoo/sdk

Set up the client​

import { Vengtoo } from '@vengtoo/sdk'

const vengtoo = new Vengtoo({
  apiKey: process.env.VENGTOO_API_KEY,
})

Built-in middleware​

The SDK includes Express middleware out of the box:

import express from 'express'

const app = express()

// Resolve the authenticated caller from each request (set by your auth layer).
const subject = (req) => ({ external_id: req.user.id, type: 'user' })

app.get('/documents/:id', vengtoo.middleware('document', 'read', subject), (req, res) => {
  res.json({ id: req.params.id, content: '...' })
})

app.put('/documents/:id', vengtoo.middleware('document', 'write', subject), (req, res) => {
  res.json({ updated: true })
})

app.delete('/documents/:id', vengtoo.middleware('document', 'delete', subject), (req, res) => {
  res.json({ deleted: true })
})

Custom subject extraction​

If your user ID comes from a JWT or session:

app.get('/documents/:id',
  vengtoo.middleware('document', 'read', (req) => ({ external_id: req.user.sub, type: 'user' })),
  handler
)

Manual check​

For more control, call check() directly:

app.get('/documents/:id', async (req, res) => {
  const allowed = await vengtoo.check(
    { id: req.user.id, type: 'user', roles: req.user.roles },
    'read',
    { id: req.params.id, type: 'document' }
  )

  if (!allowed) {
    return res.status(403).json({ error: 'forbidden' })
  }

  res.json({ id: req.params.id, content: '...' })
})

Full response with reason​

app.get('/documents/:id', async (req, res) => {
  const resp = await vengtoo.evaluate({
    subject: { id: req.user.id, type: 'user' },
    resource: { id: req.params.id, type: 'document' },
    action: { name: 'read' },
  })

  if (!resp.decision) {
    return res.status(403).json({
      error: 'forbidden',
      reason: resp.context.reason,
    })
  }

  res.json({ id: req.params.id })
})

Using the local agent​

const vengtoo = new Vengtoo({
  baseUrl: 'http://localhost:8181',
})

Same middleware, same API, just faster responses.

Error handling​

import { VengtooError } from '@vengtoo/sdk'

app.use((err, req, res, next) => {
  if (err instanceof VengtooError) {
    if (err.isAuthError) {
      return res.status(500).json({ error: 'Vengtoo configuration error' })
    }
  }
  next(err)
})
Last updated on