API Overview

Programmatic access to Torvus Security

The Torvus Security API provides programmatic access to vaults, documents, recipients, policies, and check-ins. Build integrations, automate workflows, and extend the platform.

Getting Started

Prerequisites

Plan Requirements:

Professional or Enterprise plan (API access not available on Free/Standard)

What You'll Need:

Torvus Security account
API key (generated in Settings → API Keys)
HTTPS client (curl, Postman, or HTTP library)

Base URL

All API requests are made to:

https://api.torvussecurity.com/v1

API Versions:

v1: Current stable version (recommended)

Authentication

All API requests require authentication via API key in the Authorization header:

curl https://api.torvussecurity.com/v1/vaults \
  -H "Authorization: Bearer YOUR_API_KEY"

See Authentication for detailed documentation.

Quick Example

Create a vault and upload a document:

# 1. Create vault
curl -X POST https://api.torvussecurity.com/v1/vaults \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Test Vault",
    "description": "Created via API"
  }'

# Response: {"vault_id": "vault_abc123", ...}

# 2. Upload document
curl -X POST https://api.torvussecurity.com/v1/vaults/vault_abc123/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "tags=test,api"

See Quickstart Guide for complete tutorial.

API Capabilities

Vaults API

Manage vaults programmatically:

Create, read, update, delete vaults
List all vaults
Get vault metadata and storage usage
Configure vault settings

Use Cases:

Automated vault provisioning
Vault management dashboards
Integration with existing systems

Endpoints: Vaults API Documentation

Documents API

Upload and manage documents:

Upload single or multiple documents
Download documents
Update document metadata (tags, descriptions)
Delete documents
Search documents

Use Cases:

Automated document backup
Bulk document uploads
Document synchronization from other systems

Endpoints: Documents API Documentation

Recipients API

Manage vault recipients:

Add recipients to vaults
Update recipient permissions
Remove recipients
List all recipients

Use Cases:

Automated recipient management
Recipient provisioning workflows
Integration with HR systems

Endpoints: Recipients API Documentation

Policies API

Configure release policies:

Create policies (inactivity, manual, date-based, death certificate)
Update policy settings
Pause/resume policies
Delete policies
List all policies

Use Cases:

Automated policy configuration
Policy templates
Compliance enforcement

Endpoints: Policies API Documentation

Check-ins API

Complete check-ins programmatically:

Complete check-in for inactivity policy
Get check-in status
View check-in history

Use Cases:

Automated check-ins from monitoring systems
Integration with heartbeat services
Custom check-in workflows

Endpoints: Check-ins API Documentation

API Features

RESTful Design

Standard HTTP Methods:

GET: Retrieve resources
POST: Create resources
PUT: Update resources (replace)
PATCH: Update resources (partial)
DELETE: Delete resources

HTTP Status Codes:

200 OK: Success
201 Created: Resource created
204 No Content: Success (no response body)
400 Bad Request: Invalid request
401 Unauthorized: Invalid API key
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

JSON Request/Response

Content Type: All requests and responses use JSON (except file uploads, which use multipart/form-data).

Request Example:

{
  "name": "Personal Vault",
  "description": "Important documents",
  "tags": ["personal", "family"]
}

Response Example:

{
  "vault_id": "vault_abc123",
  "name": "Personal Vault",
  "description": "Important documents",
  "created_at": "2025-10-07T12:00:00Z",
  "storage_used": 0,
  "storage_limit": 107374182400
}

Pagination

List Endpoints support pagination:

GET /v1/vaults?page=1&per_page=50

Parameters:

page: Page number (default: 1)
per_page: Results per page (default: 50, max: 100)

Response Headers:

X-Total-Count: 250
X-Page: 1
X-Per-Page: 50
X-Total-Pages: 5

Response Body:

{
  "data": [...],
  "pagination": {
    "total": 250,
    "page": 1,
    "per_page": 50,
    "total_pages": 5
  }
}

Filtering and Sorting

Filter by Fields:

GET /v1/vaults?tag=personal&created_after=2025-01-01

Sort Results:

GET /v1/vaults?sort=created_at&order=desc

Parameters:

sort: Field to sort by
order: asc (ascending) or desc (descending)

Rate Limiting

Rate Limits by Plan:

Professional: 1,000 requests/hour
Enterprise: 10,000 requests/hour (or custom)

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1696694400

429 Response (rate limit exceeded):

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 15 minutes.",
  "retry_after": 900
}

See Rate Limiting for details.

Error Handling

Error Response Format:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    "field": "name",
    "reason": "Name is required"
  }
}

Common Error Codes:

invalid_request: Malformed request
authentication_failed: Invalid API key
permission_denied: Insufficient permissions
resource_not_found: Requested resource doesn't exist
validation_failed: Request validation error
rate_limit_exceeded: Too many requests

See Error Handling for complete list.

Security

HTTPS Only

All API requests must use HTTPS. HTTP requests are rejected.

# ✅ Correct
curl https://api.torvussecurity.com/v1/vaults

# ❌ Incorrect (rejected)
curl http://api.torvussecurity.com/v1/vaults

API Key Security

Best Practices:

Never commit API keys to version control
Store API keys in environment variables
Rotate API keys regularly (every 90 days recommended)
Use separate API keys for different environments (dev, staging, production)
Revoke unused API keys immediately

Environment Variable Example:

export TORVUS_API_KEY="your_api_key_here"
curl -H "Authorization: Bearer $TORVUS_API_KEY" \
  https://api.torvussecurity.com/v1/vaults

IP Whitelisting

Enterprise Plan: Restrict API access to specific IP addresses.

Configuration:

Navigate to Settings → API Keys
Select API key
Add allowed IP addresses (CIDR notation supported)
Save changes

Example: Only allow requests from 203.0.113.0/24

Audit Logging

All API requests are logged:

Endpoint accessed
HTTP method
Request timestamp
Response status
IP address
User agent

Access Audit Logs:

Navigate to Settings → Audit Logs
Filter by "API Activity"
Export as CSV (Professional/Enterprise)

SDKs and Libraries

Official SDKs

JavaScript/TypeScript:

npm install @torvus/sdk

import { TorvusClient } from '@torvus/sdk';

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

Python:

pip install torvus

from torvus import TorvusClient

client = TorvusClient(api_key=os.environ['TORVUS_API_KEY'])
vaults = client.vaults.list()

Go:

go get github.com/torvus-security/torvus-go

import "github.com/torvus-security/torvus-go"

client := torvus.NewClient(os.Getenv("TORVUS_API_KEY"))
vaults, _ := client.Vaults.List()

Community Libraries

Ruby: gem install torvus-ruby (community-maintained) PHP: composer require torvus/sdk (community-maintained) Java: torvus-java on Maven Central (community-maintained)

API Versioning

Version Policy

Current Version: v1 (stable)

Versioning Strategy:

Major version in URL path (/v1, /v2)
Backward-compatible changes released without version bump
Breaking changes trigger new major version

Backward-Compatible Changes:

Adding new endpoints
Adding optional request parameters
Adding new response fields
Adding new error codes

Breaking Changes (require new version):

Removing endpoints
Removing request/response fields
Changing field types
Changing authentication method

Deprecation Policy

Notice Period: 12 months minimum before deprecation

Deprecation Process:

Announcement: 12 months before deprecation
Deprecation Header: Deprecation: true header added to responses
Migration Guide: Published with alternatives
Sunset: Endpoint removed after deprecation period

Support and Resources

Documentation

Quickstart Guide: Get started in 15 minutes
Authentication: API key management and authentication
Vaults API: Vault management endpoints
Rate Limiting: Rate limits and quotas
Error Codes: Complete error reference

API Changelog

Subscribe to Updates: api-changelog@torvussecurity.com

Recent Changes:

2025-10-01: Added PATCH /v1/vaults/:id for partial updates
2025-09-15: Increased rate limits for Enterprise plan
2025-08-20: Added webhook support for vault release notifications

Support

API Support:

Professional: Email support (response within 4 hours)
Enterprise: Dedicated API support (response within 1 hour)

Contact: api-support@torvussecurity.com

Include in Support Request:

Request ID (from X-Request-ID response header)
Timestamp
HTTP status code
Full error response

Community

Developer Forum: community.torvussecurity.com GitHub Issues: github.com/torvus-security/api-issues Stack Overflow: Tag questions with torvus-api

Next Steps

Get Started with Quickstart: Complete tutorial in 15 minutes
Generate API Key: Create your first API key
Explore Endpoints: Browse API reference
Try Example Code: Working examples in multiple languages

Last Updated: October 7, 2025

Getting Started​

Prerequisites​

Base URL​

Authentication​

Quick Example​

API Capabilities​

Vaults API​

Documents API​

Recipients API​

Policies API​

Check-ins API​

API Features​

RESTful Design​

JSON Request/Response​

Pagination​

Filtering and Sorting​

Rate Limiting​

Error Handling​

Security​

HTTPS Only​

API Key Security​

IP Whitelisting​

Audit Logging​

SDKs and Libraries​

Official SDKs​

Community Libraries​

API Versioning​

Version Policy​

Deprecation Policy​

Support and Resources​

Documentation​

API Changelog​

Support​

Community​

Next Steps​

Getting Started

Prerequisites

Base URL

Authentication

Quick Example

API Capabilities

Vaults API

Documents API

Recipients API

Policies API

Check-ins API

API Features

RESTful Design

JSON Request/Response

Pagination

Filtering and Sorting

Rate Limiting

Error Handling

Security

HTTPS Only

API Key Security

IP Whitelisting

Audit Logging

SDKs and Libraries

Official SDKs

Community Libraries

API Versioning

Version Policy

Deprecation Policy

Support and Resources

Documentation

API Changelog

Support

Community

Next Steps