Skip to main content

SDKs & Client Libraries

Official SDKs and tools for integrating Torvus Security into your applications.

Official SDKs​

JavaScript / TypeScript​

Package: @torvus/api-client Status: v0.1.0-alpha (Foundation Complete)

npm install @torvus/api-client
# or
yarn add @torvus/api-client
# or
pnpm add @torvus/api-client

Quick Start:

import { TorvusClient } from '@torvus/api-client';

const client = new TorvusClient({
  apiKey: process.env.TORVUS_API_KEY!,
});

// Create a vault
const vault = await client.post('/v1/vaults', {
  name: 'Personal Documents',
  description: 'Important files',
  check_in_frequency: 'weekly',
});

console.log(`Vault created with ID: ${vault.id}`);

// Get all vaults
const vaults = await client.get('/v1/vaults');

// Update vault
const updated = await client.patch(`/v1/vaults/${vault.id}`, {
  name: 'Updated Name',
});

// Delete vault
await client.delete(`/v1/vaults/${vault.id}`);

Documentation: JavaScript/TypeScript SDK Guide

Python​

Package: torvus-sdk Status: v0.1.0-alpha (Foundation Complete)

pip install torvus-sdk

Quick Start:

from torvus_sdk import TorvusClient

client = TorvusClient(api_key="sk_live_your_api_key_here")

# Create a vault
vault = client.post("/v1/vaults", {
    "name": "Personal Documents",
    "description": "Important files",
    "check_in_frequency": "weekly",
})

print(f"Vault created with ID: {vault['id']}")

# Get all vaults
vaults = client.get("/v1/vaults")

# Update vault
updated = client.patch(f"/v1/vaults/{vault['id']}", {
    "name": "Updated Name",
})

# Delete vault
client.delete(f"/v1/vaults/{vault['id']}")

Documentation: Python SDK Guide

Postman Collection​

Format: Postman Collection v2.1.0 Status: Complete

Import the official Postman collection for interactive API exploration:

  1. Download from: /postman/Torvus-API.postman_collection.json
  2. Import into Postman
  3. Configure environment with your API key
  4. Start making requests!

The collection includes:

  • 20+ endpoints organized into folders
  • Environment variables for easy testing
  • Example request bodies
  • Pre-configured authentication

Documentation: Postman Collection Guide

SDK Features​

All official SDKs (v0.1.0) include:

✅ Type Safety: Full TypeScript type definitions and Python type hints ✅ Error Handling: Custom error classes with type checking methods ✅ Automatic Retries: Exponential backoff for 5xx server errors (1s, 2s, 4s, 8s) ✅ Debug Logging: Optional debug mode for request/response logging ✅ Configuration: Customizable timeout, base URL, and retry behavior ✅ HTTP Methods: GET, POST, PATCH, PUT, DELETE convenience methods

Planned for v0.2.0+:

  • ⏳ High-level resource methods (e.g., client.vaults.create())
  • ⏳ Pagination helper utilities
  • ⏳ Webhook signature verification
  • ⏳ File upload/download helpers
  • ⏳ Request caching and rate limit tracking

Installation​

JavaScript/TypeScript​

npm install @torvus/api-client

Requirements: Node.js 16+ or modern browser

Python​

pip install torvus-sdk

Requirements: Python 3.8+

Authentication​

All SDKs use API key authentication via the X-API-Key header:

JavaScript/TypeScript​

import { TorvusClient } from '@torvus/api-client';

// Method 1: Pass API key directly
const client = new TorvusClient({
  apiKey: 'sk_live_your_api_key_here',
});

// Method 2: Use environment variable (recommended)
const client = new TorvusClient({
  apiKey: process.env.TORVUS_API_KEY!,
});

Python​

from torvus_sdk import TorvusClient

# Method 1: Pass API key directly
client = TorvusClient(api_key="sk_live_your_api_key_here")

# Method 2: Use environment variable (recommended)
import os
client = TorvusClient(api_key=os.getenv("TORVUS_API_KEY"))

Get your API key: app.torvussecurity.com/settings/api-keys

Configuration Options​

JavaScript/TypeScript​

const client = new TorvusClient({
  // Required: Your API key
  apiKey: 'sk_live_your_api_key_here',

  // Optional: Override base URL (default: https://api.torvussecurity.com)
  baseUrl: 'https://api.torvussecurity.com',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Max retries for 5xx errors (default: 3)
  maxRetries: 3,

  // Optional: Enable debug logging (default: false)
  debug: false,

  // Optional: Custom headers for all requests
  headers: {
    'X-Custom-Header': 'value',
  },
});

Python​

client = TorvusClient(
    # Required: Your API key
    api_key="sk_live_your_api_key_here",

    # Optional: Override base URL (default: https://api.torvussecurity.com)
    base_url="https://api.torvussecurity.com",

    # Optional: Request timeout in seconds (default: 30)
    timeout=30,

    # Optional: Max retries for 5xx errors (default: 3)
    max_retries=3,

    # Optional: Enable debug logging (default: False)
    debug=False,

    # Optional: Custom headers for all requests
    headers={
        "X-Custom-Header": "value",
    },
)

Error Handling​

JavaScript/TypeScript​

import { TorvusClient, TorvusApiError } from '@torvus/api-client';

const client = new TorvusClient({ apiKey: process.env.TORVUS_API_KEY! });

try {
  const vault = await client.get('/v1/vaults/invalid_id');
} catch (error) {
  if (error instanceof TorvusApiError) {
    // Handle specific error types
    if (error.isAuthenticationError()) {
      console.error('Invalid API key');
    } else if (error.isNotFoundError()) {
      console.error('Vault not found');
    } else if (error.isRateLimitError()) {
      console.error(`Rate limited. Retry after: ${error.details?.retryAfter} seconds`);
    } else if (error.isServerError()) {
      console.error('Server error, please try again');
    }

    // Access error details
    console.log('Status code:', error.statusCode);
    console.log('Error code:', error.errorCode);
    console.log('Request ID:', error.requestId);
  }
}

Available error type checkers:

  • isAuthenticationError() - 401 errors
  • isAuthorizationError() - 403 errors
  • isNotFoundError() - 404 errors
  • isRateLimitError() - 429 errors
  • isServerError() - 5xx errors
  • isClientError() - 4xx errors

Python​

from torvus_sdk import TorvusClient, TorvusApiError

client = TorvusClient(api_key=os.getenv("TORVUS_API_KEY"))

try:
    vault = client.get("/v1/vaults/invalid_id")
except TorvusApiError as error:
    # Handle specific error types
    if error.is_authentication_error():
        print("Invalid API key")
    elif error.is_not_found_error():
        print("Vault not found")
    elif error.is_rate_limit_error():
        retry_after = error.details.get("retryAfter")
        print(f"Rate limited. Retry after: {retry_after} seconds")
    elif error.is_server_error():
        print("Server error, please try again")

    # Access error details
    print(f"Status code: {error.status_code}")
    print(f"Error code: {error.error_code}")
    print(f"Request ID: {error.request_id}")

Available error type checkers:

  • is_authentication_error() - 401 errors
  • is_authorization_error() - 403 errors
  • is_not_found_error() - 404 errors
  • is_rate_limit_error() - 429 errors
  • is_server_error() - 5xx errors
  • is_client_error() - 4xx errors

Retry Logic​

Both SDKs automatically retry requests that fail with 5xx server errors:

  • Retry attempts: 3 by default (configurable via maxRetries / max_retries)
  • Backoff strategy: Exponential (1s, 2s, 4s, 8s, etc.)
  • Retried status codes: 500, 501, 502, 503, 504
// JavaScript: Configure custom retry behavior
const client = new TorvusClient({
  apiKey: process.env.TORVUS_API_KEY!,
  maxRetries: 5, // Retry up to 5 times
});
# Python: Configure custom retry behavior
client = TorvusClient(
    api_key=os.getenv("TORVUS_API_KEY"),
    max_retries=5,  # Retry up to 5 times
)

Rate Limiting​

The API enforces rate limits based on your tier:

TierRequests/DayRequests/Minute
Free1,00010
Professional100,000100
Enterprise1,000,0001,000

When rate limited (HTTP 429), the SDK throws a TorvusApiError with error type checker isRateLimitError() / is_rate_limit_error() returning true. The error details include a retryAfter field indicating seconds to wait.

Learn More​

Contributing​

We welcome contributions to our SDKs!

Monorepo: github.com/torvus-security/torvus

  • JavaScript SDK: packages/api-client/
  • Python SDK: packages/python-sdk/
  • Postman Collection: postman/

Support​

Last Updated: October 13, 2025