Authentication & Security
Ztrace Documentation
Secure your API requests with proper authentication. Ztrace supports multiple authentication methods for different use cases.
Keep Your Keys Safe
Never expose API keys in client-side code or public repositories. Use environment variables and server-side requests.
API Key Types
| Type | Prefix | Use Case | Permissions |
|---|---|---|---|
| Live | zt_live_ | Production applications | Full access |
| Test | zt_test_ | Development/testing | Limited, no billing |
| Restricted | zt_rk_ | Limited scope access | Configurable |
Authentication Methods
auth.ts
TypeScript
1// Method 1: Bearer Token Authentication2<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> headers = {3 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Authorization</span>'</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Bearer</span> '</span> + process.<span class="text-cyan-300">env</span>.<span class="text-cyan-300">ZTRACE_API_KEY</span>,4 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Content</span>-<span class="text-yellow-300">Type</span>'</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">'application/json'</span>,5 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">X</span>-<span class="text-yellow-300">Request</span>-<span class="text-yellow-300">ID</span>'</span>: crypto.<span class="text-blue-400">randomUUID</span>(),6 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">X</span>-<span class="text-yellow-300">Client</span>-<span class="text-yellow-300">Version</span>'</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-orange-400">2.<span class="text-cyan-300">0</span></span>.<span class="text-orange-400">0</span>'</span>7};8 9// Method 2: API Key Header10<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> headersAlt = {11 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">X</span>-<span class="text-yellow-300">API</span>-<span class="text-yellow-300">Key</span>'</span>: process.<span class="text-cyan-300">env</span>.<span class="text-cyan-300">ZTRACE_API_KEY</span>,12 <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">Content</span>-<span class="text-yellow-300">Type</span>'</span>: <span class="text-emerald-<span class="text-orange-400">400</span>">'application/json'</span>13};14 15// Making authenticated requests16<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> response = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> <span class="text-blue-400">fetch</span>(<span class="text-emerald-<span class="text-orange-400">400</span>">'https://api.<span class="text-cyan-300">ztrace</span>.<span class="text-cyan-300">ai</span>/v2/analyze'</span>, {17 method: <span class="text-emerald-<span class="text-orange-400">400</span>">'<span class="text-yellow-300">POST</span>'</span>,18 headers,19 body: <span class="text-yellow-300">JSON</span>.<span class="text-blue-400">stringify</span>({20 image_url: <span class="text-emerald-<span class="text-orange-400">400</span>">'https://example.<span class="text-cyan-300">com</span>/image.<span class="text-cyan-300">jpg</span>'</span>,21 options: {22 model: <span class="text-emerald-<span class="text-orange-400">400</span>">'geo-v3'</span>,23 confidence_threshold: <span class="text-orange-400">0.<span class="text-cyan-300">8</span></span>24 }25 })26});27 28<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>if</span></span> (!response.<span class="text-cyan-300">ok</span>) {29 <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> error = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> response.<span class="text-blue-400">json</span>();30 <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>throw</span> <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>new</span> <span class="text-blue-400"><span class="text-yellow-300">Error</span></span>(<span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-emerald-<span class="text-orange-400">400</span>"</span>>`<span class="text-yellow-300">API</span> <span class="text-yellow-300">Error</span>: ${error.<span class="text-cyan-300">message</span>}`</span>);31}32 33<span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>const</span> data = <span <span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>class</span>=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>><span class=<span class="text-emerald-<span class="text-orange-400">400</span>">"text-purple-<span class="text-orange-400">400</span> font-medium"</span>>await</span></span> response.<span class="text-blue-400">json</span>();Security Best Practices
Store API keys in environment variables, never in code
Use restricted keys with minimal permissions when possible
Rotate keys regularly and revoke unused keys
Implement request signing for sensitive operations
Use HTTPS for all API communications
Monitor API usage for anomalies
Set up IP allowlisting for production keys
Last updated December 2025
Was this helpful?