Authentication
AxiTrace uses two types of API keys to authenticate requests: Public Keys for client-side integrations and Secret Keys for server-side requests. Understanding when to use each is critical for security.
API Keys Overview
Every workspace in AxiTrace has two authentication credentials:
| Key Type | Format | Use Case | Security Level |
|---|---|---|---|
Public Key |
pk_live_xxx... |
Client-side (JavaScript SDK) | Safe to expose in browser |
Secret Key |
sk_live_xxx... |
Server-side (API calls) | Never expose publicly |
Public Key
The Public Key (pk_live_...) is designed for client-side integrations
where the key will be visible in your website's source code. This is similar to how analytics tools
like Google Analytics or Segment work.
Security Features
Public Keys are protected by multiple security layers:
- Domain Verification - Only requests from verified domains are accepted
- CORS Protection - Browser security prevents unauthorized cross-origin requests
- Rate Limiting - Per-IP and per-workspace limits prevent abuse
- Bot Filtering - Automated traffic is detected and filtered
Custom Tracking Domain
For client-side tracking, you'll use a custom tracking domain that you configure in your
workspace settings. This is a subdomain on your own domain (e.g., axi.yourdomain.com) that
points to AxiTrace servers.
Using a custom subdomain (like axi.yourdomain.com) helps avoid ad blockers and
provides better first-party cookie support. Configure your custom domain in Workspace settings → Tracking & domains.
How to Use
Include the Public Key when initializing the JavaScript SDK with your custom tracking domain. Synchronous loading is recommended for maximum reliability:
<!-- Load SDK synchronously (recommended) -->
<script src="https://axi.yourdomain.com/axitrack.js"></script>
<script>
Axitrace.init({
apiUrl: 'https://axi.yourdomain.com',
publicKey: 'pk_live_YOUR_PUBLIC_KEY'
});
</script>
See the JavaScript SDK Installation Guide for complete setup instructions including Facebook/TikTok pixel integration.
The SDK will send requests to your custom domain with the Public Key in the header:
POST /track HTTP/1.1
Host: axi.yourdomain.com
X-VeliTrack-Public-Key: pk_live_YOUR_PUBLIC_KEY
Content-Type: application/json
Before using the Public Key, you must verify your domain in the AxiTrace dashboard. Go to Workspace settings → Tracking & domains to add and verify your domain.
Secret Key
The Secret Key (sk_live_...) provides full authentication for
server-side integrations. It bypasses domain verification and should only be used in secure,
server-side environments.
Never expose your Secret Key! Do not include it in:
- Client-side JavaScript code
- Mobile app source code
- Public Git repositories
- Browser developer tools
- Client-side logs or error messages
When to Use Secret Key
- Server-side event tracking - Backend services sending events
- Webhook handlers - Processing payment completions, order updates
- Data import scripts - Batch importing historical data
- Backend integrations - E-commerce platforms, CRM systems
How to Use
The Secret Key is used with HTTP Basic Authentication. Use the Secret Key
as the username and leave the password empty. Server-side requests should use
stat.axitrace.com as the base URL (or your custom tracking domain if configured):
# Note the colon after the secret key (empty password)
curl -X POST https://stat.axitrace.com/v1/subscribe \
-u "sk_live_YOUR_SECRET_KEY:" \
-H "Content-Type: application/json" \
-H "User-Agent: MyApp/1.0" \
-d '{
"client_id": "user-123",
"email": "customer@example.com",
"subscription_type": "newsletter"
}'
<?php
$secretKey = 'sk_live_YOUR_SECRET_KEY';
$data = [
'client_id' => 'user-123',
'email' => 'customer@example.com',
'subscription_type' => 'newsletter'
];
$ch = curl_init('https://stat.axitrace.com/v1/subscribe');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_USERPWD, $secretKey . ':'); // Note: empty password
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'User-Agent: MyApp/1.0'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$result = json_decode($response, true);
echo "Event tracked: " . $result['eventId'];
}
import requests
secret_key = 'sk_live_YOUR_SECRET_KEY'
response = requests.post(
'https://stat.axitrace.com/v1/subscribe',
auth=(secret_key, ''), # Empty password
headers={
'Content-Type': 'application/json',
'User-Agent': 'MyApp/1.0'
},
json={
'client_id': 'user-123',
'email': 'customer@example.com',
'subscription_type': 'newsletter'
}
)
if response.status_code == 200:
result = response.json()
print(f"Event tracked: {result['eventId']}")
const axios = require('axios');
const secretKey = 'sk_live_YOUR_SECRET_KEY';
const response = await axios.post(
'https://stat.axitrace.com/v1/subscribe',
{
client_id: 'user-123',
email: 'customer@example.com',
subscription_type: 'newsletter'
},
{
auth: {
username: secretKey,
password: '' // Empty password
},
headers: {
'Content-Type': 'application/json',
'User-Agent': 'MyApp/1.0'
}
}
);
console.log('Event tracked:', response.data.eventId);
Authorization Header Format
If you prefer to construct the Authorization header manually, use Base64 encoding
with the format secret_key: (note the trailing colon):
POST /v1/subscribe HTTP/1.1
Host: stat.axitrace.com
Authorization: Basic {base64 of "sk_live_YOUR_SECRET_KEY:"}
Content-Type: application/json
User-Agent: MyApp/1.0
The Base64 value is computed as:
# Generate the Authorization header value
echo -n "sk_live_YOUR_SECRET_KEY:" | base64
Comparing Authentication Methods
| Feature | Public Key | Secret Key |
|---|---|---|
| Safe for browsers | ✓ Yes | ✗ No |
| Domain verification required | ✓ Yes | - No |
| CORS protection | ✓ Yes | - N/A |
| Server-side use | △ Limited | ✓ Recommended |
| Authentication method | Header: X-VeliTrack-Public-Key |
HTTP Basic Auth |
Best Practices
For Client-Side (JavaScript)
- Always use the Public Key in browser environments
- Verify your domains in the AxiTrace dashboard
- The SDK automatically handles authentication
For Server-Side
- Store the Secret Key in environment variables
- Never commit secrets to version control
- Use a secrets manager in production (e.g., AWS Secrets Manager, Vault)
- Rotate keys periodically and if compromised
- Always include a descriptive
User-Agentheader
# Good: Store in environment variable
export AXITRACE_SECRET_KEY="sk_live_..."
# Bad: Hardcoded in code
$secretKey = "sk_live_..."; // Don't do this!
Finding Your API Keys
You can find both keys in your AxiTrace dashboard:
- Log in to axitrace.com
- Open your workspace and click Workspace settings in the sidebar
- Open Tracking & domains and find your keys in the Container Information card
If you regenerate your Secret Key, all existing server-side integrations using the old key will stop working. Update your integrations immediately after regeneration.
Error Responses
Authentication errors return standard HTTP status codes:
| Status Code | Meaning | Solution |
|---|---|---|
401 Unauthorized |
Missing or invalid authentication | Check your API key is correct and properly formatted |
403 Forbidden |
Workspace inactive or domain not verified | Verify your domain or check workspace status |
429 Too Many Requests |
Rate limit exceeded | Reduce request frequency or contact support |