Skip to main content

Node.js SDK

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

Install​

npm install @authzx/sdk

Quick start​

import { AuthzX } from '@authzx/sdk'

const authzx = new AuthzX({ apiKey: 'azx_...' })

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

Using with the local agent​

const authzx = new AuthzX({ baseUrl: 'http://localhost:8181' })

Full response​

const resp = await authzx.authorize({
  subject: { id: 'user-123', type: 'user', roles: ['editor'] },
  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 { AuthzX } from '@authzx/sdk'

const app = express()
const authzx = new AuthzX({ apiKey: 'azx_...' })

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

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

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

Options​

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

Error handling​

import { AuthzX, AuthzXError } from '@authzx/sdk'

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

Types​

interface Subject {
  id: string
  type: string
  properties?: Record<string, unknown>  // "attributes" is accepted as an alias
  roles?: string[]
}

interface Resource {
  id: string
  type: string
  properties?: Record<string, unknown>  // "attributes" is accepted as an alias
}

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
}