API Reference

Node.js SDK

The official TypeScript/Node.js client for the XtraSecurity API. Built with native caching, TypeScript definitions, and Zero-Trust injection.

Installation

>_Terminal

npm install @xtrasecurity/sdk

Configuration

The SDK provides a primary wrapper class, XtraClient. It accepts an XtraClientOptions object during instantiation.

>_Terminal

import { XtraClient } from '@xtrasecurity/sdk';
 
// Initialize the client
const client = new XtraClient({
  projectId: 'prj_123456789',
  cacheTtl: 60000 // Cache secrets in-memory for 60 seconds
});

Option	Type	Default	Description
token	`string`	`process.env.XTRA_TOKEN`	The API Token used for authentication.
projectId	`string`	`process.env.XTRA_PROJECT_ID`	The default project ID for all secret operations.
apiUrl	`string`	`https://www.xtrasecurity.in/api`	Override the base URL for self-hosted Enterprise instances.
cache	`boolean`	`true`	Enables in-memory caching to prevent rate-limiting on high-traffic apps.
cacheTtl	`number`	`30000`	Time-to-live for cached secrets in milliseconds (default: 30 seconds).

Core Methods

getSecrets()

Fetches all secrets for a specific environment and branch, returning a standard key-value dictionary. This method automatically utilizes the in-memory cache if enabled.

>_Terminal

// Fetch from production (main branch)
const secrets = await client.getSecrets('production');
console.log(secrets.DATABASE_URL);
 
// Fetch from a specific branch and bypass cache
const previewSecrets = await client.getSecrets('staging', undefined, 'feature/new-ui', true);

Parameter	Type	Description
env	`'development' \| 'staging' \| 'production'`	Required. The target environment.
projectId?	`string`	Optional override for the default projectId.
branch?	`string`	Optional. Target a specific environment branch (defaults to 'main').
noCache?	`boolean`	Optional. If true, forces a network request bypassing the in-memory cache.

injectSecrets()

A convenience method that fetches secrets and immediately populates process.env. This is the recommended approach for serverless functions and Express backends.

Pro Tip

Call this method as early as possible in your application lifecycle (e.g., at the top of your index.ts).

>_Terminal

import { XtraClient } from '@xtrasecurity/sdk';
 
const client = new XtraClient();
 
// Instantly inject secrets into process.env
await client.injectSecrets('production', { 
  projectId: 'prj_123456789',
  branch: 'feature/new-ui',
  override: true // Overwrite existing local environment variables
});
 
// Now you can use them normally across your application
console.log(process.env.DATABASE_URL);

clearCache()

Manually flushes the in-memory secret cache. Useful when responding to webhook events notifying you of secret changes.

>_Terminal

client.clearCache();

Advanced API Access

For power users building custom internal tools, XtraClient exposes the raw auto-generated service classes. You have full programmatic access to Projects, Teams, Audits, Branches, and Notifications.

>_Terminal

import { XtraClient, XtraError } from '@xtrasecurity/sdk';
 
const client = new XtraClient();
 
try {
  // Access the raw auto-generated API classes for advanced management
  const projectInfo = await client.projects.getProject('prj_123456789');
  
  // Create an environment branch programmatically
  await client.branches.createBranch('prj_123456789', {
    name: 'hotfix/api-v2',
    baseEnv: 'production'
  });
} catch (error) {
  if (error instanceof XtraError) {
    console.error("XtraSecurity Error:", error.message);
  }
}

Error Handling

All internal SDK errors are thrown as instances of the XtraError class. Network or HTTP errors from the underlying API will throw standard Axios errors containing status codes and response data.