API Key Management & Security
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
API Key Management and Security in TrueLens provides the infrastructure necessary for developers to integrate AI-powered content verification into third-party applications. The system focuses on secure authentication via Bearer tokens, rate limiting based on subscription tiers, and cryptographic integrity for processed assets. This ensures that only authorized clients can access analysis endpoints while maintaining the provenance of verified documents.
The security architecture encompasses the lifecycle of an API key—from generation in the developer dashboard to validation during high-frequency requests. It also integrates with a document signing system that uses SHA-256 hashing and digital signatures to provide tamper-evident results.
Sources: truelens-app/src/app/developers/page.tsx:125-135, truelens-app/src/lib/types.ts:63-72
API Authentication & Authorization
TrueLens employs a standard API key-based authentication mechanism. Developers must include their unique key in the Authorization header of every request using the Bearer scheme.
Authentication Flow
When a request is made to the API, the backend validates the presence and validity of the API key before proceeding to the analysis pipeline.
The sequence above illustrates the verification process for every inbound API call.
Sources: truelens-app/src/app/developers/page.tsx:57-81, truelens-app/src/app/api/v1/scans/route.ts:7-25
API Key Schema
The ApiKey interface defines the structure of credentials used within the system, including metadata for tracking usage and enforcing security constraints like expiration and scopes.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the key record. |
userId | string | Owner of the API key. |
keyPrefix | string | Publicly visible prefix of the key (e.g., tl_live_). |
scopes | string[] | Permissions associated with the key (e.g., scans:read, docs:write). |
rateLimit | number | Maximum requests allowed per day. |
expiresAt | string? | Optional timestamp for key revocation. |
Sources: truelens-app/src/lib/types.ts:63-72
Security Infrastructure
The platform implements several layers of security to protect both the API and the documents being processed.
Rate Limiting & Tiers
Usage is constrained by pricing tiers, which dictate the capacity and features available to an API key.
- Free: Limited to 50 scans per month and basic text/URL analysis.
- Pro: Supports 5,000 scans per month and up to 1,000 API calls per day.
- Enterprise: Offers unlimited scans, custom webhooks, and on-premise machine learning options.
Sources: truelens-app/src/app/developers/page.tsx:185-225
Document Integrity & Signing
For sensitive documents like Aadhaar cards or invoices, TrueLens provides a cryptographic signature. This ensures that once a document is verified, any subsequent tampering can be detected.
The flow shows how a document moves from raw upload to a cryptographically signed state.
Sources: truelens-app/src/app/documents/page.tsx:216-240, truelens-app/src/app/verify/page.tsx:106-135
Data Models for Security
Key data structures support the security verification process:
- DocumentSignature: Contains the
documentHash, the actualsignature, and thepublicKeyrequired for verification. - VerificationResult: Returned by the verification service to confirm if a
signatureValidboolean is true and to provide atrustScore.
Sources: truelens-app/src/lib/types.ts:54-61, truelens-app/src/app/verify/page.tsx:15-27
Implementation Details
API Request Examples
Authentication is handled uniformly across different environments using the Bearer token pattern.
Node.js Implementation:
const response = await fetch('https://api.truelens.app/v1/scans', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
},
body: JSON.stringify({
url: 'https://example.com/article',
contentType: 'url'
})
});
Sources: truelens-app/src/app/developers/page.tsx:66-73
Backend Proxy Security
The Next.js application acts as a secure proxy to the FastAPI backend. It handles the mapping of keys and ensures that internal backend URLs are not exposed directly to the client.
Sources: truelens-app/src/app/api/v1/scans/route.ts:5-10, truelens-app/src/app/api/v1/scans/route.ts:38-42
Conclusion
API Key Management & Security in TrueLens is designed to be developer-friendly while maintaining enterprise-grade protection. By combining tiered rate limiting, scope-based authorization, and cryptographic document signing, the system ensures that authenticity verification remains both accessible and untamperable.