Skip to main content

Postman Collection

Official Postman collection for interactive API exploration and testing.

Format: Postman Collection v2.1.0 Status: Complete (20+ endpoints) Repository: github.com/torvus-security/torvus

Quick Start​

1. Download Collection Files​

Download these two files from the repository:

  1. Collection: Torvus-API.postman_collection.json
  2. Environment: Torvus-API.postman_environment.json

2. Import into Postman​

Import Collection​

  1. Open Postman
  2. Click Import button (top left)
  3. Select or drag Torvus-API.postman_collection.json
  4. Collection appears in your sidebar under "Collections"

Import Environment​

  1. Click Environments icon in the sidebar
  2. Click Import
  3. Select Torvus-API.postman_environment.json
  4. Click Torvus API - Production to activate

3. Configure API Key​

  1. Click Environments → Torvus API - Production
  2. Set API_KEY to your actual API key
  3. Get your key from: app.torvussecurity.com/settings/api-keys
  4. Click Save

4. Test Your Setup​

  1. Open Utilities folder in the collection
  2. Run Get Feature Flags (Public) (no auth required)
  3. Run Authentication → Get Current User (whoami) (requires API key)

If both succeed, you're ready to go! ✅

Collection Structure​

The collection includes 20+ endpoints organized into logical folders:

📁 Authentication (5 endpoints)​

WebAuthn passwordless authentication and user identity:

  • Get Current User (whoami) - Returns authenticated user's profile
  • Generate WebAuthn Registration Options - Start credential registration
  • Verify WebAuthn Registration - Complete credential registration
  • Generate WebAuthn Authentication Options - Start authentication flow
  • Verify WebAuthn Authentication - Complete authentication flow

📁 Vaults (8 endpoints)​

Secure vault management and operations:

  • List Vaults - Get all vaults with pagination
  • Create Vault - Create a new secure vault
  • Get Vault - Retrieve vault details by ID
  • Update Vault - Modify vault properties
  • Delete Vault - Permanently delete vault
  • Check In to Vault - Record proof-of-life check-in
  • List Vault Documents - Get documents in vault
  • Initiate Document Upload - Start multipart upload

📁 Documents (4 endpoints)​

Document upload, download, and management:

  • Finalize Document Upload - Complete upload after file transfer
  • Get Document Metadata - Retrieve document details
  • Delete Document - Permanently delete document
  • Download Document - Get signed download URL

📁 Recipients (4 endpoints)​

Release recipient management and verification:

  • List Recipients - Get all recipients
  • Add Recipient - Create new recipient
  • Send Verification Email - Send verification to recipient
  • Get Verification Status - Check recipient verification

📁 Utilities (2 endpoints)​

Public utilities and system information:

  • Get Feature Flags (Public) - Public feature flags (no auth)
  • Get User Statistics - User account statistics

Environment Variables​

The environment includes the following variables:

VariableDescriptionExample
baseUrlAPI base URLhttps://api.torvussecurity.com/v1
API_KEYYour API key (required)sk_live_abc123...
user_idUser UUID (auto-populated)123e4567-...
vault_idVault UUID (auto-populated)123e4567-...
document_idDocument UUID (auto-populated)123e4567-...
recipient_idRecipient UUID (auto-populated)123e4567-...

Note: Resource IDs (vault_id, document_id, etc.) are automatically populated from responses. You can also set them manually.

Authentication​

All requests (except /v1/flags) require authentication via API key:

  • Header: X-API-Key: sk_live_your_api_key_here
  • Location: Set in environment variable API_KEY
  • Scope: Collection-level auth (automatically applied to all requests)

The collection is pre-configured with collection-level authentication, so you only need to set your API key in the environment.

Example Workflow​

Here's a typical workflow using the collection:

Step 1: Create a Vault​

POST /vaults
{
  "name": "My Vault",
  "vault_type": "personal"
}

Response: Copy the id field

Step 2: Save Vault ID​

  1. Copy id from response
  2. Go to Environments → Torvus API - Production
  3. Set vault_id to the copied value
  4. Click Save

Step 3: Upload a Document​

POST /vaults/{{vault_id}}/documents/initiate
{
  "filename": "document.pdf",
  "content_type": "application/pdf",
  "size": 1048576
}

Response: Note the upload_url for file upload

Step 4: Upload File to Signed URL​

Use the upload_url from step 3 to upload your file (external to Postman, or use a new request).

Step 5: Finalize Upload​

POST /documents/finalize
{
  "document_id": "{{document_id}}"
}

Step 6: Check In​

POST /vaults/{{vault_id}}/checkin

Advanced Features​

Pre-request Scripts​

Add scripts to automatically extract and save response values:

// Save vault_id from response
pm.test("Save vault ID", function () {
    const response = pm.response.json();
    pm.environment.set("vault_id", response.id);
});

Tests​

Add test assertions to validate responses:

// Test: Verify successful response
pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has data field", function () {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.have.property('data');
});

Collection Runner​

Run multiple requests in sequence:

  1. Click Collections → Torvus Security Platform API
  2. Click Run (top right)
  3. Select requests to run
  4. Click Run Torvus Security Platform API

Rate Limiting​

Be aware of rate limits based on your tier:

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

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets

Troubleshooting​

401 Unauthorized​

Problem: API key not recognized

Solutions:

  • Verify API key is correct (check for extra spaces)
  • Check API key hasn't expired
  • Ensure key is set in Environments → Torvus API - Production → API_KEY
  • Verify environment is activated (dropdown in top right)

404 Not Found​

Problem: Resource doesn't exist

Solutions:

  • Check that the vault_id/document_id/recipient_id is correct
  • Verify you're using the correct base URL
  • Ensure the resource belongs to your account
  • Check for typos in the request URL

429 Rate Limit Exceeded​

Problem: Too many requests

Solutions:

  • Wait for the rate limit to reset (check X-RateLimit-Reset header)
  • Reduce request frequency
  • Consider upgrading your tier
  • Use Collection Runner delay feature (Settings → Delay between requests)

500 Internal Server Error​

Problem: Server error

Solutions:

  • Check API status: status.torvussecurity.com
  • Retry the request (may be temporary)
  • Contact support with request ID from error response
  • Check request body for malformed data

Tips & Best Practices​

1. Use Pre-request Scripts​

Automatically set environment variables from responses:

// Extract and save IDs from responses
pm.test("Save response IDs", function () {
    const response = pm.response.json();
    if (response.vault_id) {
        pm.environment.set("vault_id", response.vault_id);
    }
    if (response.document_id) {
        pm.environment.set("document_id", response.document_id);
    }
});

2. Create Tests​

Add test scripts to validate responses automatically:

pm.test("Status code is 2xx", function () {
    pm.expect(pm.response.code).to.be.oneOf([200, 201, 202, 204]);
});

pm.test("Response time is acceptable", function () {
    pm.expect(pm.response.responseTime).to.be.below(2000);
});

3. Fork the Collection​

Create a personal copy to customize without losing updates:

  1. Hover over collection name
  2. Click ··· (three dots)
  3. Select Create a fork
  4. Customize your fork freely

4. Create Multiple Environments​

Set up separate environments for different scenarios:

  • Development: Point to sandbox API
  • Staging: Pre-production testing
  • Production: Live API with production keys

5. Use Collection Variables​

For values that don't change between requests:

  1. Right-click collection name
  2. Select Edit
  3. Go to Variables tab
  4. Add collection-level variables

6. Monitor with Postman Monitor​

Set up automated monitoring:

  1. Click collection ··· menu
  2. Select Monitor collection
  3. Configure schedule and notifications
  4. Get alerts if API changes or fails

Creating Custom Requests​

Adding a New Request​

  1. Right-click on folder
  2. Select Add request
  3. Configure request details:
    • Method: GET, POST, PATCH, DELETE, PUT
    • URL: {{baseUrl}}/your-endpoint
    • Headers: Auto-inherited from collection
    • Body: JSON data for POST/PATCH/PUT

Example: Custom Vault Query​

GET {{baseUrl}}/vaults?limit=5&status=active

Headers:
- X-API-Key: {{API_KEY}} (auto-inherited)

Exporting and Sharing​

Export Collection​

  1. Right-click collection name
  2. Select Export
  3. Choose Collection v2.1 (recommended)
  4. Save file

Share with Team​

  • Public link: Click Share → Get public link
  • Workspace: Move to shared workspace
  • Export/Import: Share JSON file via email/Slack

Additional Resources​

Contributing​

Found an issue with the collection? Please open an issue on GitHub: github.com/torvus-security/torvus/issues

License​

MIT © Torvus Security

Last Updated: October 13, 2025