API v1 Test Endpoint

Verify your API key authentication

The test endpoint allows you to verify that your API key is valid and properly configured. Use this endpoint to test authentication before making production API calls.

---

Endpoint

GET https://api.torvussecurity.com/api/v1/test

Base URL: https://api.torvussecurity.com

Path: /api/v1/test

Method: GET

Authentication: Required (X-API-Key header)

---

Authentication

API Key Header

API v1 uses the X-API-Key header for authentication:

curl https://api.torvussecurity.com/api/v1/test \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

Header Name: X-API-Key (case-insensitive, x-api-key also works)

Format: sk_live_ or sk_test_ followed by base64-encoded key

---

API Key Types

Live Keys

Prefix: sk_live_

Use: Production environments

Characteristics:

• Full access to production resources
• Rate limits enforced based on tier
• Audit logging enabled
• Permanent records in production database

Example: sk_live_zGgF9rvG-NO7POa46KdHH2r_BcIvet4c8YmrYgLpXnc

---

Test Keys

Prefix: sk_test_

Use: Development and testing

Characteristics:

• Access to test mode resources
• Separate from production data
• Higher rate limits for testing
• Safe for development environments

Example: sk_test_abc123def456ghi789jkl012mno345pqr678stu901

---

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your API key (sk_live_* or sk_test_*)

Example Request

curl https://api.torvussecurity.com/api/v1/test \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

---

Response

Success Response (200 OK)

{
  "success": true,
  "message": "Authentication successful",
  "key_info": {
    "key_id": "01JBG7XKQM9F3Y8W2Z5N4P1R6T",
    "key_name": "Production API Key",
    "user_id": "01JBG7XKQM9F3Y8W2Z5N4P1R6T",
    "tier_id": "01JBG7XKQM9F3Y8W2Z5N4P1R6T",
    "rate_limits": {
      "requests_per_day": 10000,
      "requests_per_minute": 100
    }
  },
  "timestamp": "2025-10-17T14:30:00.000Z"
}

Response Fields:

• success (boolean): Always true for successful authentication
• message (string): Human-readable success message
• key_info (object): Information about the API key
  • key_id (string): Unique identifier for this API key (ULID format)
  • key_name (string): Descriptive name assigned to the key
  • user_id (string): ID of the user who owns this key
  • tier_id (string): Subscription tier ID determining rate limits
  • rate_limits (object): Rate limit configuration
    • requests_per_day (number): Maximum requests allowed per day
    • requests_per_minute (number): Maximum requests allowed per minute
• timestamp (string): ISO 8601 timestamp of the response

Response Headers:

X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Response-Time: 145
Content-Type: application/json

---

Error Responses

Missing API Key (401)

Error: No X-API-Key header provided

{
  "error": "unauthorized",
  "message": "Missing X-API-Key header",
  "code": "MISSING_API_KEY"
}

HTTP Status: 401 Unauthorized

Fix: Include X-API-Key header in your request

---

Invalid API Key Format (401)

Error: API key doesn't start with sk_live_ or sk_test_

{
  "error": "unauthorized",
  "message": "Invalid API key format",
  "code": "INVALID_API_KEY_FORMAT"
}

HTTP Status: 401 Unauthorized

Fix: Verify your API key starts with sk_live_ or sk_test_

---

Invalid API Key (401)

Error: API key not found in database

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": "INVALID_API_KEY"
}

HTTP Status: 401 Unauthorized

Possible Causes:

• API key was deleted or revoked
• API key is incorrect or corrupted
• Using test key against production endpoint (or vice versa)

Fix: Generate a new API key from the platform dashboard

---

API Key Not Active (401)

Error: API key exists but is not active

{
  "error": "unauthorized",
  "message": "API key is revoked",
  "code": "API_KEY_NOT_ACTIVE"
}

HTTP Status: 401 Unauthorized

Possible Statuses:

• revoked: Key was manually revoked
• suspended: Key was suspended due to policy violation
• expired: Key passed its expiration date

Fix: Generate a new API key or reactivate the existing key

---

API Key Expired (401)

Error: API key has passed its expiration date

{
  "error": "unauthorized",
  "message": "API key has expired",
  "code": "API_KEY_EXPIRED"
}

HTTP Status: 401 Unauthorized

Fix: Generate a new API key

---

Method Not Allowed (405)

Error: Using incorrect HTTP method (only GET is allowed)

{
  "error": "Method not allowed"
}

HTTP Status: 405 Method Not Allowed

Fix: Use GET method instead of POST, PUT, DELETE, etc.

---

Internal Server Error (500)

Error: Unexpected server error

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "code": "INTERNAL_ERROR",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

HTTP Status: 500 Internal Server Error

Action:

• Retry the request after a short delay
• If the error persists, contact support with the request_id

---

Rate Limiting

Rate Limits by Tier

Tier	Requests/Minute	Requests/Day
Free	10	1,000
Professional	60	10,000
Enterprise	300	100,000

Rate Limit Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1697558400

Headers:

• X-RateLimit-Limit: Maximum requests allowed in the current window
• X-RateLimit-Remaining: Number of requests remaining in the current window
• X-RateLimit-Reset: Unix timestamp when the rate limit resets

Rate Limit Exceeded (429)

Error: Too many requests

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 45 seconds.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 45
}

HTTP Status: 429 Too Many Requests

Headers:

Retry-After: 45
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1697558400

Action: Wait for the time specified in retry_after (seconds) before retrying

---

Code Examples

cURL

# Test API key
curl https://api.torvussecurity.com/api/v1/test \
  -H "X-API-Key: sk_live_YOUR_API_KEY_HERE"

# Store API key in environment variable
export TORVUS_API_KEY="sk_live_YOUR_API_KEY_HERE"

curl https://api.torvussecurity.com/api/v1/test \
  -H "X-API-Key: $TORVUS_API_KEY"

---

JavaScript (Fetch API)

const apiKey = process.env.TORVUS_API_KEY;

const response = await fetch('https://api.torvussecurity.com/api/v1/test', {
  headers: {
    'X-API-Key': apiKey
  }
});

const data = await response.json();

if (response.ok) {
  console.log('Authentication successful!');
  console.log('Rate limits:', data.key_info.rate_limits);
} else {
  console.error('Authentication failed:', data.message);
}

---

JavaScript (Axios)

const axios = require('axios');

const apiKey = process.env.TORVUS_API_KEY;

try {
  const response = await axios.get(
    'https://api.torvussecurity.com/api/v1/test',
    {
      headers: {
        'X-API-Key': apiKey
      }
    }
  );

  console.log('Authentication successful!');
  console.log('Key ID:', response.data.key_info.key_id);
  console.log('Rate limits:', response.data.key_info.rate_limits);
} catch (error) {
  console.error('Error:', error.response?.data || error.message);
}

---

Python (Requests)

import os
import requests

api_key = os.environ['TORVUS_API_KEY']

response = requests.get(
    'https://api.torvussecurity.com/api/v1/test',
    headers={'X-API-Key': api_key}
)

if response.status_code == 200:
    data = response.json()
    print('Authentication successful!')
    print(f"Key ID: {data['key_info']['key_id']}")
    print(f"Rate limits: {data['key_info']['rate_limits']}")
else:
    print(f"Error: {response.json()['message']}")

---

Go

package main

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

type TestResponse struct {
    Success   bool   `json:"success"`
    Message   string `json:"message"`
    KeyInfo   struct {
        KeyID      string `json:"key_id"`
        KeyName    string `json:"key_name"`
        UserID     string `json:"user_id"`
        TierID     string `json:"tier_id"`
        RateLimits struct {
            RequestsPerDay    int `json:"requests_per_day"`
            RequestsPerMinute int `json:"requests_per_minute"`
        } `json:"rate_limits"`
    } `json:"key_info"`
    Timestamp string `json:"timestamp"`
}

func main() {
    apiKey := os.Getenv("TORVUS_API_KEY")

    req, _ := http.NewRequest("GET", "https://api.torvussecurity.com/api/v1/test", nil)
    req.Header.Set("X-API-Key", apiKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var data TestResponse
    json.NewDecoder(resp.Body).Decode(&data)

    if resp.StatusCode == 200 {
        fmt.Println("Authentication successful!")
        fmt.Printf("Key ID: %s\n", data.KeyInfo.KeyID)
        fmt.Printf("Rate limits: %+v\n", data.KeyInfo.RateLimits)
    } else {
        fmt.Printf("Error: %s\n", data.Message)
    }
}

---

Testing Best Practices

Environment Variables

Store API keys in environment variables, never hardcode them:

# .env (add to .gitignore!)
TORVUS_API_KEY=sk_live_YOUR_API_KEY_HERE

// Load from .env file
require('dotenv').config();
const apiKey = process.env.TORVUS_API_KEY;

---

Separate Test and Production Keys

Use different API keys for each environment:

# Development
export TORVUS_API_KEY=sk_test_dev_key_here

# Production
export TORVUS_API_KEY=sk_live_prod_key_here

---

Validate Before Making Requests

Test authentication before processing:

async function validateApiKey() {
  const response = await fetch('https://api.torvussecurity.com/api/v1/test', {
    headers: { 'X-API-Key': process.env.TORVUS_API_KEY }
  });

  if (!response.ok) {
    throw new Error('Invalid API key');
  }

  return response.json();
}

// Use in your application startup
validateApiKey()
  .then(data => {
    console.log('API key valid. Rate limits:', data.key_info.rate_limits);
    // Continue with application logic
  })
  .catch(error => {
    console.error('API key validation failed:', error);
    process.exit(1);
  });

---

Architecture

API Gateway

The test endpoint is served through Tyk API Gateway at api.torvussecurity.com:

Client Request
      ↓
[Tyk Gateway] (api.torvussecurity.com)
      ↓
[Platform API] (platform.torvussecurity.com)
      ↓
[Supabase PostgreSQL]

Gateway Features:

• CORS handling
• Request/response logging
• SSL termination
• DDoS protection
• Load balancing

---

Security

API Key Hashing:

• API keys are hashed with SHA-256 before storage
• Only the hash is stored in the database
• Keys cannot be recovered if lost

Request Tracking:

• Every request receives a unique X-Request-ID
• All requests are logged with Sentry for observability
• Failed authentication attempts are tracked

Rate Limiting:

• Enforced at the application layer
• Based on API key tier configuration
• Prevents abuse and ensures fair usage

---

Monitoring

Response Headers

Every response includes monitoring headers:

X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Response-Time: 145

Use these headers for:

• Debugging failed requests
• Performance monitoring
• Support inquiries

---

Error Tracking

All errors are automatically tracked in Sentry with:

• Request ID for correlation
• API key ID (not the key itself)
• Error type and category
• Response time
• Severity level

---

FAQ

Why X-API-Key instead of Bearer token?

The API v1 architecture uses X-API-Key header for simplicity and compatibility with API gateways. This pattern is widely supported and easier to implement across different platforms.

Can I use both x-api-key and X-API-Key?

Yes, the header is case-insensitive. Both x-api-key and X-API-Key work correctly.

How do I get an API key?

API keys are managed through the platform dashboard at platform.torvussecurity.com. Navigate to Settings → API Keys to generate a new key.

What happens if my API key is compromised?

Immediately revoke the compromised key through the platform dashboard and generate a new one. Update all applications using the old key to use the new key.

Do API keys expire?

API keys can have optional expiration dates set when created. Check the expires_at field in your API key settings. We recommend rotating keys every 90 days for security.

---

Next Steps

• API Overview: Learn about the API
• Authentication Guide: Learn about API key management
• Rate Limiting: Understand rate limit policies
• Error Handling: Handle errors gracefully

---

Last Updated: October 17, 2025