AxiTrace API authentication - how to generate and use your Public Key and Secret Key to send server-side events.

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.

Why Custom Domains?

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
Domain Verification Required

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.

Critical Security Warning

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-Agent header
# 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:

  1. Log in to axitrace.com
  2. Open your workspace and click Workspace settings in the sidebar
  3. Open Tracking & domains and find your keys in the Container Information card
Regenerating Keys

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