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

TypePrefixUse CasePermissions
Livezt_live_Production applicationsFull access
Testzt_test_Development/testingLimited, no billing
Restrictedzt_rk_Limited scope accessConfigurable

Authentication Methods

auth.ts
TypeScript
1// Method 1: Bearer Token Authentication
2<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 Header
10<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 requests
16<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?