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
});
OptionTypeDefaultDescription
tokenstringprocess.env.XTRA_TOKENThe API Token used for authentication.
projectIdstringprocess.env.XTRA_PROJECT_IDThe default project ID for all secret operations.
apiUrlstringhttps://www.xtrasecurity.in/apiOverride the base URL for self-hosted Enterprise instances.
cachebooleantrueEnables in-memory caching to prevent rate-limiting on high-traffic apps.
cacheTtlnumber30000Time-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);
ParameterTypeDescription
env'development' | 'staging' | 'production'Required. The target environment.
projectId?stringOptional override for the default projectId.
branch?stringOptional. Target a specific environment branch (defaults to 'main').
noCache?booleanOptional. 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.