API Authentication

Secure your API requests

All Torvus API requests require authentication using API keys. This guide covers API key generation, authentication methods, and security best practices.

API Key Overview

What are API Keys?

API keys are secure tokens that identify your application and grant access to the Torvus API.

Key Features:

Unique per application/environment
Scoped permissions (Read, Write, Delete)
Optional expiration dates
IP whitelisting (Enterprise)
Revocable anytime

Generate API Key

Create New API Key

Log in to app.torvussecurity.com
Navigate to Settings → API Keys
Click "Generate New API Key"
Configure key settings:

Key Name:

Descriptive name for identification
Example: "Production Server", "Development", "CI/CD Pipeline"

Permissions:

☑️ Read: View vaults, documents, recipients, policies
☑️ Write: Create and update resources
☑️ Delete: Delete resources

Expiration:

90 days (recommended)
1 year
Never (not recommended for production)

IP Whitelist (Enterprise only):

Restrict API key to specific IP addresses
CIDR notation supported (e.g., 203.0.113.0/24)
Leave empty to allow all IPs

Click "Generate Key"

Save Your API Key

Critical: Copy your API key immediately. It will only be shown once.

torvus_sk_live_abc123xyz789...

Store Securely:

Environment variables (recommended)
Secret management systems (AWS Secrets Manager, HashiCorp Vault)
Password managers (1Password, LastPass)

Never:

Commit to version control
Share via email or messaging
Hardcode in application code
Store in plaintext files

Authentication Methods

Method 1: Bearer Token (Recommended)

Use Authorization header with Bearer scheme:

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

Format: Authorization: Bearer <api_key>

Method 2: Environment Variable

Store API key in environment variable:

export TORVUS_API_KEY="your_api_key_here"

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

Benefits:

Keeps key out of code
Easy to rotate
Works across applications

Method 3: Configuration File

Store in configuration file (outside version control):

{
  "api_key": "your_api_key_here",
  "base_url": "https://api.torvussecurity.com/v1"
}

Add to .gitignore:

config.json
.env
*.env

API Key Types

Live Keys

Prefix: torvus_sk_live_

Use: Production environments

Characteristics:

Full access to production resources
Rate limits enforced
Audit logging enabled

Test Keys

Prefix: torvus_sk_test_

Use: Development and testing

Characteristics:

Access to test mode resources
Separate from production data
Higher rate limits
No charges for API usage

Permissions

Read Permission

Grants Access To:

GET /v1/vaults
GET /v1/vaults/:id
GET /v1/vaults/:id/documents
GET /v1/vaults/:id/recipients
GET /v1/vaults/:id/policies
GET /v1/check-ins

Use Cases:

Monitoring dashboards
Read-only integrations
Reporting systems

Write Permission

Grants Access To:

POST /v1/vaults
PUT /v1/vaults/:id
PATCH /v1/vaults/:id
POST /v1/vaults/:id/documents
POST /v1/vaults/:id/recipients
POST /v1/vaults/:id/policies
POST /v1/check-ins

Use Cases:

Automated uploads
Vault provisioning
Recipient management

Delete Permission

Grants Access To:

DELETE /v1/vaults/:id
DELETE /v1/vaults/:id/documents/:id
DELETE /v1/vaults/:id/recipients/:id
DELETE /v1/vaults/:id/policies/:id

Use Cases:

Cleanup scripts
Vault lifecycle management
Resource deprovisioning

Warning: Deletions are permanent. Use with caution.

Security Best Practices

Key Rotation

Recommendation: Rotate API keys every 90 days.

Rotation Process:

Generate new API key
Update applications with new key
Test applications
Revoke old API key
Monitor for errors

Zero-Downtime Rotation:

Generate second API key
Deploy applications with new key
Verify all applications updated
Revoke first API key

Environment Separation

Use Separate Keys for each environment:

Environment	Key Name	Permissions	Expiration
Development	Dev Key	Read, Write	90 days
Staging	Staging Key	Read, Write	90 days
Production	Prod Key	Read, Write	90 days
CI/CD	CI Key	Read	Never

IP Whitelisting (Enterprise)

Restrict API access to specific IP addresses:

Configuration:

Navigate to API key settings
Add allowed IPs (CIDR notation supported)
Save changes

Examples:

Single IP: 203.0.113.5
IP range: 203.0.113.0/24
Multiple IPs: 203.0.113.5, 198.51.100.10

Benefits:

Prevents key use from unauthorized locations
Additional security layer
Compliance requirement for some organizations

Key Storage

Recommended Storage Methods:

AWS Secrets Manager:

import boto3
import json

client = boto3.client('secretsmanager')
response = client.get_secret_value(SecretId='torvus-api-key')
api_key = json.loads(response['SecretString'])['api_key']

HashiCorp Vault:

vault kv get -field=api_key secret/torvus

Environment Variables:

export TORVUS_API_KEY="$(cat /secure/path/api-key.txt)"

Docker Secrets:

services:
  app:
    secrets:
      - torvus_api_key

secrets:
  torvus_api_key:
    external: true

Least Privilege

Principle: Grant minimum permissions required.

Examples:

Monitoring Dashboard (read-only):

✅ Read permission
❌ Write permission
❌ Delete permission

Automated Backup (upload only):

✅ Read permission
✅ Write permission
❌ Delete permission

Cleanup Script (full access):

✅ Read permission
✅ Write permission
✅ Delete permission

Managing API Keys

List All API Keys

View all active API keys:

Navigate to Settings → API Keys
See list of all keys with:
- Key name
- Permissions
- Last used date
- Expiration date
- Creation date

Revoke API Key

Immediately invalidate an API key:

Navigate to Settings → API Keys
Find key to revoke
Click "Revoke"
Confirm revocation

Result: All requests with revoked key return 401 Unauthorized.

Use Cases:

Key compromised
Key no longer needed
Employee departure
Security incident

View API Key Usage

Monitor API key activity:

Navigate to Settings → API Keys
Click key name
View usage statistics:
- Total requests (last 30 days)
- Requests by endpoint
- Error rate
- Last used timestamp
- IP addresses used from

Authentication Errors

401 Unauthorized

Error:

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

Possible Causes:

API key incorrect or malformed
API key expired
API key revoked
Missing Authorization header

Solutions:

Verify API key is correct
Check API key hasn't expired
Generate new API key if revoked
Ensure Authorization: Bearer YOUR_KEY header present

403 Forbidden

Error:

{
  "error": "permission_denied",
  "message": "API key lacks required permissions"
}

Possible Causes:

API key missing required permission (Read, Write, Delete)
IP address not whitelisted (Enterprise)
Accessing another user's resources

Solutions:

Check API key permissions in settings
Add missing permissions
Add IP to whitelist
Verify resource ownership

Testing Authentication

Verify API Key

Test authentication with account endpoint:

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

Success (200 OK):

{
  "account_id": "acc_abc123",
  "email": "you@example.com",
  "plan": "professional",
  "api_version": "v1"
}

Failure (401 Unauthorized):

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

Test Permissions

Test specific permissions:

Test Read Permission:

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

Test Write Permission:

curl -X POST https://api.torvussecurity.com/v1/vaults \
  -H "Authorization: Bearer $TORVUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Vault"}'

Test Delete Permission:

curl -X DELETE https://api.torvussecurity.com/v1/vaults/vault_test \
  -H "Authorization: Bearer $TORVUS_API_KEY"

Code Examples

Python

import os
import requests

API_KEY = os.environ['TORVUS_API_KEY']
BASE_URL = 'https://api.torvussecurity.com/v1'

def get_vaults():
    response = requests.get(
        f'{BASE_URL}/vaults',
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    return response.json()

vaults = get_vaults()

JavaScript (Node.js)

const axios = require('axios');

const API_KEY = process.env.TORVUS_API_KEY;
const BASE_URL = 'https://api.torvussecurity.com/v1';

async function getVaults() {
  const response = await axios.get(`${BASE_URL}/vaults`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });
  return response.data;
}

getVaults().then(vaults => console.log(vaults));

Go

package main

import (
    "fmt"
    "net/http"
    "os"
)

func main() {
    apiKey := os.Getenv("TORVUS_API_KEY")
    client := &http.Client{}

    req, _ := http.NewRequest("GET", "https://api.torvussecurity.com/v1/vaults", nil)
    req.Header.Add("Authorization", "Bearer " + apiKey)

    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Ruby

require 'net/http'
require 'json'

api_key = ENV['TORVUS_API_KEY']
uri = URI('https://api.torvussecurity.com/v1/vaults')

request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{api_key}"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

vaults = JSON.parse(response.body)

Rate Limiting

API keys are subject to rate limiting:

Rate Limits:

Professional: 1,000 requests/hour
Enterprise: 10,000 requests/hour

Headers:

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

See Rate Limiting for details.

Audit Logging

All API requests are logged:

Logged Information:

API key used
Endpoint accessed
HTTP method
Response status
IP address
Timestamp
Request ID

Access Logs:

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

Next Steps

Quickstart Guide: Make your first API request
Vaults API: Explore vault endpoints
Rate Limiting: Understand rate limits
Error Handling: Handle API errors

Last Updated: October 7, 2025

API Key Overview​

What are API Keys?​

Generate API Key​

Create New API Key​

Save Your API Key​

Authentication Methods​

Method 1: Bearer Token (Recommended)​

Method 2: Environment Variable​

Method 3: Configuration File​

API Key Types​

Live Keys​

Test Keys​

Permissions​

Read Permission​

Write Permission​

Delete Permission​

Security Best Practices​

Key Rotation​

Environment Separation​

IP Whitelisting (Enterprise)​

Key Storage​

Least Privilege​

Managing API Keys​

List All API Keys​

Revoke API Key​

View API Key Usage​

Authentication Errors​

401 Unauthorized​

403 Forbidden​

Testing Authentication​

Verify API Key​

Test Permissions​

Code Examples​

Python​

JavaScript (Node.js)​

Go​

Ruby​

Rate Limiting​

Audit Logging​

Next Steps​

API Key Overview

What are API Keys?

Generate API Key

Create New API Key

Save Your API Key

Authentication Methods

Method 1: Bearer Token (Recommended)

Method 2: Environment Variable

Method 3: Configuration File

API Key Types

Live Keys

Test Keys

Permissions

Read Permission

Write Permission

Delete Permission

Security Best Practices

Key Rotation

Environment Separation

IP Whitelisting (Enterprise)

Key Storage

Least Privilege

Managing API Keys

List All API Keys

Revoke API Key

View API Key Usage

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Verify API Key

Test Permissions

Code Examples

Python

JavaScript (Node.js)

Go

Ruby

Rate Limiting

Audit Logging

Next Steps