API v1.0

Developer Documentation

Integrate dual-layer biometric authentication into your application with TerraLink's REST API

REST API

Low Latency

Enterprise Ready

Getting Started

Begin integrating TerraLink in minutes

1. Obtain API Credentials

Sandbox Environment

Use test mode credentials for development. All verifications return predictable results without consuming production credits.

2. Base URL

https://api.terralink.io/v1

All API requests should be made to this base URL.

3. Quick Test

Test your API key with a simple health check:

curl -X GET https://api.terralink.io/v1/health \
  -H "x-api-key: YOUR_API_KEY"

Authentication

Secure your API requests

API Key Authentication

Include your API key in the x-api-key header for all requests.

GET /v1/challenges HTTP/1.1
Host: api.terralink.io
x-api-key: tlk_pro_your_api_key_here
Content-Type: application/json

Security Best Practices

• Never expose API keys in client-side code or public repositories
• Rotate keys regularly (recommended every 90 days)
• Use environment variables to store credentials
• Implement rate limiting on your application layer

API Key Formats

Production

tlk_pro_xxxxxxxxxxxxxxxx

Test

tlk_test_xxxxxxxxxxxxxxxx

Voice Verification

Verify human speakers using voice biometrics

1. Request Challenge

Generate a unique challenge phrase for the user to speak.

POST /v1/challenges
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "user_id": "user_12345"
}

2. Submit Voice Recording

Upload the user's voice recording as base64-encoded audio.

Audio Requirements

• Format: WAV or MP3
• Sample rate: 16kHz recommended
• Duration: 2-10 seconds optimal
• Size limit: 10MB

curl -X POST https://api.terralink.io/v1/verify \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_nonce": "chall_abc123",
    "user_id": "user_12345",
    "audio_base64": "UklGRiQAAABXQVZF..."
  }'

3. Response Format

{
  "decision": "ACCEPT",
  "confidence_score": 0.94,
  "spoof_score": 0.02,
  "is_spoof": false,
  "verification_id": "ver_xyz789",
  "timestamp": "2025-12-26T10:30:00Z",
  "latency_ms": 324
}

decision: ACCEPT, REJECT, or SPOOF_DETECTED

confidence_score: Match confidence (0.0 - 1.0)

spoof_score: Likelihood of synthetic/replayed audio (0.0 - 1.0)

Agent Signatures (.mhz)

Authenticate AI agents with behavioral profiles

What are Agent Signatures?

Agent signatures create unique behavioral fingerprints for AI assistants, allowing you to verify that a specific AI instance is handling user requests (not a malicious impersonator).

Create Agent Signature

POST /v1/agents
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "name": "CustomerServiceBot",
  "traits": {
    "logic": 0.75,
    "empathy": 0.85,
    "creativity": 0.60,
    "assertiveness": 0.70
  }
}

Verify Agent Behavior

Validate that an agent's current behavior matches its registered signature.

POST /v1/agents/{agent_id}/verify
x-api-key: YOUR_API_KEY
Content-Type: application/json

{
  "interaction_log": [
    {"role": "user", "content": "Help me with my order"},
    {"role": "agent", "content": "I'd be happy to help..."}
  ]
}

Trait Definitions

Logic (14.3Hz)

Analytical reasoning and problem-solving patterns

Empathy (20.8Hz)

Emotional intelligence and user sentiment response

Creativity (27.3Hz)

Novel solution generation and linguistic variation

Assertiveness (33.8Hz)

Confidence level and directiveness in responses

Unified Authentication

Combine voice + agent verification for maximum security

Why Unified Authentication?

Unified mode verifies BOTH the human user (via voice) AND the AI agent (via behavioral signature) in a single request. This prevents scenarios where an attacker compromises one layer.

Request Format

POST /v1/unified/verify
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data

--boundary
Content-Disposition: form-data; name="user_id"

user_12345
--boundary
Content-Disposition: form-data; name="agent_id"

agt_abc123
--boundary
Content-Disposition: form-data; name="challenge_nonce"

chall_xyz789
--boundary
Content-Disposition: form-data; name="audio"; filename="voice.wav"
Content-Type: audio/wav

<binary audio data>
--boundary
Content-Disposition: form-data; name="interaction_log"

[{"role":"user","content":"..."}]
--boundary--

Response Format

{
  "unified_decision": "ACCEPT",
  "human_verification": {
    "decision": "ACCEPT",
    "confidence_score": 0.94,
    "spoof_score": 0.02
  },
  "agent_verification": {
    "decision": "ACCEPT",
    "drift_score": 0.08,
    "signature_match": true
  },
  "entropy_chain": {
    "binding_hash": "ec_9a7b3f...",
    "is_valid": true
  },
  "verification_id": "unified_xyz123",
  "timestamp": "2025-12-26T10:30:00Z"
}

Decision Logic

Both human AND agent pass verification

REJECT

Either human OR agent fails verification

Drift Monitoring

Track behavioral changes over time

What is Drift?

Drift measures how much an agent's behavior deviates from its registered signature over time. Gradual drift is normal (models improve), but sudden spikes may indicate compromise.

Get Drift Analytics

GET /v1/agents/{agent_id}/drift?period=7d
x-api-key: YOUR_API_KEY

Supported periods: 24h, 7d, 30d

Response Example

{
  "agent_id": "agt_abc123",
  "period": "7d",
  "summary": {
    "avg_drift": 0.12,
    "max_drift": 0.28,
    "drift_events": 15
  },
  "time_series": [
    {"timestamp": "2025-12-20T00:00:00Z", "drift": 0.08},
    {"timestamp": "2025-12-21T00:00:00Z", "drift": 0.11},
    {"timestamp": "2025-12-22T00:00:00Z", "drift": 0.28}
  ],
  "alerts": [
    {
      "timestamp": "2025-12-22T10:30:00Z",
      "level": "WARNING",
      "message": "Drift exceeded 0.2 threshold"
    }
  ]
}

Drift Thresholds

Healthy

< 0.20

Warning

0.20 - 0.35

Critical

> 0.35

Error Codes

Handle API errors gracefully

Code	Message	Resolution
400	Invalid request format	Check request body schema
401	Invalid or missing API key	Verify x-api-key header
403	API key lacks permissions	Check account plan limits
404	Resource not found	Verify agent_id or user_id exists
429	Rate limit exceeded	Implement exponential backoff
500	Internal server error	Retry with exponential backoff
503	Service temporarily unavailable	Wait and retry after 5-10 seconds

Error Response Format

{
  "error": {
    "code": "invalid_audio_format",
    "message": "Audio must be WAV or MP3 format",
    "details": {
      "received_format": "audio/ogg",
      "supported_formats": ["audio/wav", "audio/mpeg"]
    }
  },
  "request_id": "req_abc123"
}

Rate Limits & Best Practices

Optimize your integration

Rate Limits

Free Tier

100 req/hour

1,000 verifications/month

Pro Tier

1,000 req/hour

Unlimited verifications

Best Practices

Implement Retry Logic

Use exponential backoff for 5xx errors and 429 rate limit responses.

Cache Agent Signatures

Agent signatures rarely change. Cache them locally to reduce API calls.

Monitor Drift Proactively

Poll drift analytics daily to catch anomalies before they impact users.

Use Unified Mode Strategically

Unified authentication is more expensive. Use it for high-value transactions.

Need Help?

Visit the platform guide or dashboard to explore all features and get started with TerraLink.