Skip to main content

Node.js SDK

Zero dependencies. Requires Node.js 18+ (uses native fetch).

Install​

npm install @vengtoo/sdk

Source: github.com/vengtoo/vengtoo-node

Quick start​

import { Vengtoo } from '@vengtoo/sdk'

const vengtoo = new Vengtoo({ apiKey: 'azx_...' })

const decision = await vengtoo.check(
  { id: 'user-123', type: 'user' },
  { name: 'read' },
  { id: 'doc-456', type: 'document' }
)

Using with the local agent​

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

Full response​

const resp = await vengtoo.authorize({
  subject: { id: 'user-123', type: 'user' },
  resource: { id: 'doc-456', type: 'document' },
  action: { name: 'read' },
  context: { ip: '10.0.0.1' },
})
// resp.decision, resp.context.reason, resp.context.policy_id, resp.context.access_path

Express middleware​

import express from 'express'
import { Vengtoo } from '@vengtoo/sdk'

const app = express()
const vengtoo = new Vengtoo({ apiKey: 'azx_...' })

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

Extracts subject ID from the X-User-ID header by default. Customize:

vengtoo.middleware('document', 'read', (req) => req.auth.userId)

Options​

new Vengtoo({
  apiKey: 'azx_...',
  baseUrl: 'http://localhost:8181',
  timeout: 5000,      // ms, default 10000
  maxRetries: 3,      // default 2
})

Error handling​

import { Vengtoo, VengtooError } from '@vengtoo/sdk'

try {
  await vengtoo.check(subject, 'read', resource)
} catch (err) {
  if (err instanceof VengtooError) {
    if (err.isAuthError) {
      // 401 — invalid API key
    }
    if (err.isServerError) {
      // 5xx — already retried
    }
  }
}

Types​

interface Subject {
  type: string
  id?: string
  external_id?: string
  properties?: Record<string, unknown>
}

interface Resource {
  type: string
  id?: string          // defaults to "*" on the wire if neither id nor external_id set
  external_id?: string
  properties?: Record<string, unknown>
}

interface Action {
  name: string
}

interface AuthorizeRequest {
  subject: Subject
  resource: Resource
  action: Action
  context?: Record<string, unknown>
}

interface ResponseContext {
  reason: string
  policy_id?: string
  access_path?: string
}

interface AuthorizeResponse {
  decision: boolean
  context: ResponseContext
}