SDK Reference

Installation

npm install @nullbridge/sdk

Requirements: Node.js 18+, ESM or CommonJS

NullBridge class

Constructor

import pkg from '@nullbridge/sdk';
const { NullBridge } = pkg;

const nb = new NullBridge(config);

Parameter	Type	Required	Description
`licenseKey`	`string`	Yes	Your NullBridge license key
`apiUrl`	`string`	No	API base URL (default: `https://api.nullbridge.ai`)
`serverUrl`	`string`	No	License server URL
`skipLicense`	`boolean`	No	Skip license check for local dev
`autoShutdown`	`boolean`	No	Auto-exit if license is revoked (default: `true`)
`checkInterval`	`number`	No	License recheck interval in ms (default: 24h)
`debug`	`boolean`	No	Enable verbose logging

`nb.init()`

Validates the license and starts background services. Call once on application startup.

await nb.init();

Throws: NullBridgeLicenseError if the license is invalid or expired.

`nb.shutdown()`

Gracefully shuts down — flushes logs, stops heartbeats and license watchers.

await nb.shutdown();

`nb.getLicenseInfo()`

Returns the current license data.

const info = nb.getLicenseInfo();
// { customer: 'Acme Corp', plan: 'starter', ... }

`nb.getVersion()`

Returns the SDK version string.

nb.getVersion(); // '1.0.5'

nb.agents

`nb.agents.register(agent)`

Registers an AI agent with NullBridge. The agent will appear in the Agent Registry and SIEM events will be logged.

const agent = await nb.agents.register({
  id: 'my-agent-001',
  name: 'MyAgent',
  type: 'automation',
  scopes: ['read:tasks', 'write:reports'],
  metadata: {
    owner_email: 'you@company.com',
    team: 'Engineering',
    environment: 'prod',
  },
});

Parameters:

Field	Type	Required	Description
`id`	`string`	Yes	Unique agent identifier
`name`	`string`	Yes	Display name shown in dashboard
`type`	`string`	Yes	Agent type (e.g. `automation`, `orchestrator`)
`scopes`	`string[]`	No	Minimum required permission scopes
`metadata.owner_email`	`string`	No	Owner email address
`metadata.team`	`string`	No	Team name
`metadata.environment`	`string`	No	`dev`, `staging`, or `prod`

Returns: Agent object with id, name, status, and registration details.

If an agent with the same id already exists, it will be updated rather than duplicated.

Available scopes

Scope	Description
`read:claims`	Read identity claims
`write:claims`	Write identity claims
`read:policy`	Read policies
`write:policy`	Write policies
`invoke:workflow`	Trigger workflows
`read:customers`	Read customer data
`write:customers`	Write customer data
`read:repos`	Read repositories
`write:reports`	Write reports
`read:tasks`	Read tasks
`write:tasks`	Write tasks
`read:database`	Read database
`admin:infra`	Infrastructure admin
`read:secrets`	Read secrets
`invoke:deploy`	Trigger deployments
`read:audit`	Read audit logs

Agent tiers

Agents are automatically assigned a tier based on their scopes and risk profile:

Tier	Label	Credential	Max TTL
T1	Stateless	OAuth2 JWT	900s
T2	Task-Scoped	SPIFFE/SVID	1800s
T3	Orchestrator	Vault Dynamic	3600s
T4	Privileged	PAM JIT	7200s
T5	Sub-Agent	Child Token	600s

Error types

import pkg from '@nullbridge/sdk';
const { NullBridgeLicenseError, NullBridgeApiError, NullBridgeCredentialError } = pkg;

Error	Thrown when
`NullBridgeLicenseError`	License is invalid, expired, or missing
`NullBridgeApiError`	API request fails
`NullBridgeCredentialError`	Credential operation fails

try {
  await nb.init();
} catch (err) {
  if (err instanceof NullBridgeLicenseError) {
    console.error('License issue:', err.message);
  }
}

CommonJS usage

const { NullBridge } = require('@nullbridge/sdk');

async function main() {
  const nb = new NullBridge({ licenseKey: process.env.NULLBRIDGE_LICENSE_KEY });
  await nb.init();
  await nb.agents.register({ id: 'agent-001', name: 'MyAgent', type: 'automation' });
  await nb.shutdown();
}

main().catch(console.error);

Getting Started

Concepts

Reference

Installation

NullBridge class

Constructor

`nb.init()`

`nb.shutdown()`

`nb.getLicenseInfo()`

`nb.getVersion()`

nb.agents

`nb.agents.register(agent)`

Available scopes

Agent tiers

Error types

CommonJS usage

​Installation

​NullBridge class

​Constructor

​nb.init()

​nb.shutdown()

​nb.getLicenseInfo()

​nb.getVersion()

​nb.agents

​nb.agents.register(agent)

​Available scopes

​Agent tiers

​Error types

​CommonJS usage

Installation

NullBridge class

Constructor

`nb.init()`

`nb.shutdown()`

`nb.getLicenseInfo()`

`nb.getVersion()`

nb.agents

`nb.agents.register(agent)`

Available scopes

Agent tiers

Error types

CommonJS usage