API Quickstart Guide

Get started with the Torvus Security API

This guide will walk you through your first API integration, from generating an API key to making your first requests.

Prerequisites

Requirements:

Torvus Security account (Professional or Enterprise plan)
Terminal or API client (curl, Postman, Insomnia)
Basic understanding of REST APIs and HTTP

Step 1: Generate API Key

Create API Key

Log in to app.torvussecurity.com
Navigate to Settings → API Keys
Click "Generate New API Key"
Enter key details:
- Name: "Development Key" (or descriptive name)
- Permissions: Select permissions (Read, Write, Delete)
- Expiration: Choose expiration (90 days, 1 year, never)
Click "Generate Key"

Save Your API Key

Important: Copy and save your API key immediately. It will only be shown once.

your_api_key_here_abc123xyz789

Best Practice: Store API key in environment variable:

export TORVUS_API_KEY="your_api_key_here"

Step 2: Test Authentication

Verify API Key

Test your API key by fetching your account information:

curl https://api.torvussecurity.com/v1/account \
  -H "Authorization: Bearer $TORVUS_API_KEY"

Expected Response (200 OK):

{
  "account_id": "acc_abc123",
  "email": "you@example.com",
  "plan": "professional",
  "created_at": "2025-01-15T10:30:00Z"
}

If Authentication Fails (401 Unauthorized):

{
  "error": "authentication_failed",
  "message": "Invalid API key"
}

Troubleshooting:

Verify API key is correct (no extra spaces)
Check API key hasn't expired
Ensure you're using Bearer authentication scheme

Step 3: Create Your First Vault

Create Vault

curl -X POST https://api.torvussecurity.com/v1/vaults \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Test Vault",
    "description": "My first vault created via API",
    "tags": ["test", "api"]
  }'

Response (201 Created):

{
  "vault_id": "vault_abc123",
  "name": "API Test Vault",
  "description": "My first vault created via API",
  "tags": ["test", "api"],
  "created_at": "2025-10-07T14:30:00Z",
  "storage_used": 0,
  "storage_limit": 107374182400,
  "owner": {
    "user_id": "user_xyz789",
    "email": "you@example.com"
  }
}

Save the vault_id - you'll need it for subsequent requests:

export VAULT_ID="vault_abc123"

Step 4: Upload a Document

Upload File

curl -X POST https://api.torvussecurity.com/v1/vaults/$VAULT_ID/documents \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "tags=important,test" \
  -F "description=Test document uploaded via API"

Response (201 Created):

{
  "document_id": "doc_def456",
  "vault_id": "vault_abc123",
  "filename": "document.pdf",
  "size": 524288,
  "mime_type": "application/pdf",
  "tags": ["important", "test"],
  "description": "Test document uploaded via API",
  "uploaded_at": "2025-10-07T14:35:00Z",
  "checksum": "sha256:abc123..."
}

Save the document_id:

export DOCUMENT_ID="doc_def456"

Step 5: List Vault Documents

Get All Documents

curl https://api.torvussecurity.com/v1/vaults/$VAULT_ID/documents \
  -H "Authorization: Bearer $TORVUS_API_KEY"

Response (200 OK):

{
  "data": [
    {
      "document_id": "doc_def456",
      "filename": "document.pdf",
      "size": 524288,
      "mime_type": "application/pdf",
      "tags": ["important", "test"],
      "uploaded_at": "2025-10-07T14:35:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  }
}

Step 6: Add a Recipient

Create Recipient

curl -X POST https://api.torvussecurity.com/v1/vaults/$VAULT_ID/recipients \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "relationship": "spouse",
    "permission": "admin",
    "notification_email": true,
    "notification_sms": false
  }'

Response (201 Created):

{
  "recipient_id": "rec_ghi789",
  "vault_id": "vault_abc123",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "relationship": "spouse",
  "permission": "admin",
  "notification_email": true,
  "notification_sms": false,
  "created_at": "2025-10-07T14:40:00Z",
  "verified": false
}

Step 7: Create Inactivity Policy

Configure Policy

curl -X POST https://api.torvussecurity.com/v1/vaults/$VAULT_ID/policies \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inactivity",
    "check_in_frequency": "monthly",
    "grace_period_hours": 72,
    "notification_methods": ["email", "sms"],
    "recipients": ["rec_ghi789"]
  }'

Response (201 Created):

{
  "policy_id": "pol_jkl012",
  "vault_id": "vault_abc123",
  "type": "inactivity",
  "status": "active",
  "check_in_frequency": "monthly",
  "grace_period_hours": 72,
  "next_check_in": "2025-11-07T14:45:00Z",
  "recipients": ["rec_ghi789"],
  "created_at": "2025-10-07T14:45:00Z"
}

Step 8: Complete Check-in

Submit Check-in

curl -X POST https://api.torvussecurity.com/v1/check-ins \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "vault_abc123"
  }'

Response (200 OK):

{
  "check_in_id": "ci_mno345",
  "vault_id": "vault_abc123",
  "policy_id": "pol_jkl012",
  "completed_at": "2025-10-07T14:50:00Z",
  "next_check_in": "2025-11-07T14:50:00Z",
  "status": "completed"
}

Complete Example Script

Bash Script

Here's a complete script that performs all the steps above:

#!/bin/bash

# Configuration
API_KEY="your_api_key_here"
BASE_URL="https://api.torvussecurity.com/v1"

# 1. Test authentication
echo "Testing authentication..."
curl -s "$BASE_URL/account" \
  -H "Authorization: Bearer $API_KEY" | jq .

# 2. Create vault
echo "\nCreating vault..."
VAULT_RESPONSE=$(curl -s -X POST "$BASE_URL/vaults" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Test Vault",
    "description": "Created via API script"
  }')

VAULT_ID=$(echo $VAULT_RESPONSE | jq -r '.vault_id')
echo "Vault created: $VAULT_ID"

# 3. Upload document
echo "\nUploading document..."
curl -s -X POST "$BASE_URL/vaults/$VAULT_ID/documents" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@document.pdf" \
  -F "tags=test" | jq .

# 4. Add recipient
echo "\nAdding recipient..."
curl -s -X POST "$BASE_URL/vaults/$VAULT_ID/recipients" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "relationship": "spouse",
    "permission": "admin"
  }' | jq .

# 5. Create policy
echo "\nCreating inactivity policy..."
curl -s -X POST "$BASE_URL/vaults/$VAULT_ID/policies" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inactivity",
    "check_in_frequency": "monthly",
    "grace_period_hours": 72
  }' | jq .

echo "\nSetup complete!"

Python Script

import os
import requests

API_KEY = os.environ['TORVUS_API_KEY']
BASE_URL = 'https://api.torvussecurity.com/v1'
HEADERS = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# 1. Test authentication
response = requests.get(f'{BASE_URL}/account', headers=HEADERS)
print(f"Account: {response.json()}")

# 2. Create vault
vault_data = {
    'name': 'API Test Vault',
    'description': 'Created via Python'
}
response = requests.post(f'{BASE_URL}/vaults', json=vault_data, headers=HEADERS)
vault = response.json()
vault_id = vault['vault_id']
print(f"Vault created: {vault_id}")

# 3. Upload document
with open('document.pdf', 'rb') as f:
    files = {'file': f}
    data = {'tags': 'test', 'description': 'Test document'}
    response = requests.post(
        f'{BASE_URL}/vaults/{vault_id}/documents',
        files=files,
        data=data,
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    print(f"Document uploaded: {response.json()}")

# 4. Add recipient
recipient_data = {
    'name': 'Jane Doe',
    'email': 'jane@example.com',
    'relationship': 'spouse',
    'permission': 'admin'
}
response = requests.post(
    f'{BASE_URL}/vaults/{vault_id}/recipients',
    json=recipient_data,
    headers=HEADERS
)
print(f"Recipient added: {response.json()}")

# 5. Create policy
policy_data = {
    'type': 'inactivity',
    'check_in_frequency': 'monthly',
    'grace_period_hours': 72
}
response = requests.post(
    f'{BASE_URL}/vaults/{vault_id}/policies',
    json=policy_data,
    headers=HEADERS
)
print(f"Policy created: {response.json()}")

print("Setup complete!")

JavaScript (Node.js) Script

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const API_KEY = process.env.TORVUS_API_KEY;
const BASE_URL = 'https://api.torvussecurity.com/v1';
const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function main() {
  try {
    // 1. Test authentication
    const account = await axios.get(`${BASE_URL}/account`, { headers });
    console.log('Account:', account.data);

    // 2. Create vault
    const vaultData = {
      name: 'API Test Vault',
      description: 'Created via JavaScript'
    };
    const vault = await axios.post(`${BASE_URL}/vaults`, vaultData, { headers });
    const vaultId = vault.data.vault_id;
    console.log('Vault created:', vaultId);

    // 3. Upload document
    const formData = new FormData();
    formData.append('file', fs.createReadStream('document.pdf'));
    formData.append('tags', 'test');

    const document = await axios.post(
      `${BASE_URL}/vaults/${vaultId}/documents`,
      formData,
      { headers: { 'Authorization': `Bearer ${API_KEY}`, ...formData.getHeaders() } }
    );
    console.log('Document uploaded:', document.data);

    // 4. Add recipient
    const recipientData = {
      name: 'Jane Doe',
      email: 'jane@example.com',
      relationship: 'spouse',
      permission: 'admin'
    };
    const recipient = await axios.post(
      `${BASE_URL}/vaults/${vaultId}/recipients`,
      recipientData,
      { headers }
    );
    console.log('Recipient added:', recipient.data);

    // 5. Create policy
    const policyData = {
      type: 'inactivity',
      check_in_frequency: 'monthly',
      grace_period_hours: 72
    };
    const policy = await axios.post(
      `${BASE_URL}/vaults/${vaultId}/policies`,
      policyData,
      { headers }
    );
    console.log('Policy created:', policy.data);

    console.log('Setup complete!');
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
}

main();

Common Use Cases

Use Case 1: Automated Backup

Automatically upload documents to Torvus vault:

#!/bin/bash
# backup.sh - Run daily via cron

BACKUP_DIR="/path/to/backups"
VAULT_ID="vault_abc123"

for file in $BACKUP_DIR/*; do
  echo "Uploading $file..."
  curl -X POST "https://api.torvussecurity.com/v1/vaults/$VAULT_ID/documents" \
    -H "Authorization: Bearer $TORVUS_API_KEY" \
    -F "file=@$file" \
    -F "tags=backup,automated"
done

Use Case 2: Automated Check-ins

Integrate check-ins with monitoring system:

# heartbeat.py - Run periodically

import requests
import os

def check_in():
    response = requests.post(
        'https://api.torvussecurity.com/v1/check-ins',
        json={'vault_id': os.environ['VAULT_ID']},
        headers={'Authorization': f'Bearer {os.environ["TORVUS_API_KEY"]}'}
    )
    return response.json()

if __name__ == '__main__':
    result = check_in()
    print(f"Check-in completed: {result['next_check_in']}")

Use Case 3: Recipient Sync

Sync recipients from HR system:

// sync-recipients.js

const syncRecipients = async (employees) => {
  for (const employee of employees) {
    await axios.post(
      `${BASE_URL}/vaults/${VAULT_ID}/recipients`,
      {
        name: employee.name,
        email: employee.email,
        relationship: 'employee',
        permission: 'viewer'
      },
      { headers }
    );
  }
};

Troubleshooting

401 Unauthorized

Problem: API key not recognized

Solutions:

Verify API key is correct
Check API key hasn't expired
Ensure using Bearer scheme: Authorization: Bearer YOUR_KEY

403 Forbidden

Problem: Insufficient permissions

Solutions:

Check API key has required permissions (Read, Write, Delete)
Verify you're accessing your own resources
Check plan supports API access (Professional/Enterprise)

429 Too Many Requests

Problem: Rate limit exceeded

Solutions:

Slow down requests
Check X-RateLimit-Reset header for reset time
Upgrade plan for higher rate limits
Implement exponential backoff

500 Internal Server Error

Problem: Server error

Solutions:

Retry request (may be temporary)
Check API status page: status.torvussecurity.com
Contact support with request ID (from X-Request-ID header)

Next Steps

Explore API Reference:

Learn More:

Get Support:

Last Updated: October 7, 2025

Prerequisites​

Step 1: Generate API Key​

Create API Key​

Save Your API Key​

Step 2: Test Authentication​

Verify API Key​

Step 3: Create Your First Vault​

Create Vault​

Step 4: Upload a Document​

Upload File​

Step 5: List Vault Documents​

Get All Documents​

Step 6: Add a Recipient​

Create Recipient​

Step 7: Create Inactivity Policy​

Configure Policy​

Step 8: Complete Check-in​

Submit Check-in​

Complete Example Script​

Bash Script​

Python Script​

JavaScript (Node.js) Script​

Common Use Cases​

Use Case 1: Automated Backup​

Use Case 2: Automated Check-ins​

Use Case 3: Recipient Sync​

Troubleshooting​

401 Unauthorized​

403 Forbidden​

429 Too Many Requests​

500 Internal Server Error​

Next Steps​

Prerequisites

Step 1: Generate API Key

Create API Key

Save Your API Key

Step 2: Test Authentication

Verify API Key

Step 3: Create Your First Vault

Create Vault

Step 4: Upload a Document

Upload File

Step 5: List Vault Documents

Get All Documents

Step 6: Add a Recipient

Create Recipient

Step 7: Create Inactivity Policy

Configure Policy

Step 8: Complete Check-in

Submit Check-in

Complete Example Script

Bash Script

Python Script

JavaScript (Node.js) Script

Common Use Cases

Use Case 1: Automated Backup

Use Case 2: Automated Check-ins

Use Case 3: Recipient Sync

Troubleshooting

401 Unauthorized

403 Forbidden

429 Too Many Requests

500 Internal Server Error

Next Steps