Authentication

API Key Authentication

All API requests must include your API key in the X-API-Key header.

curl https://api.crbtrack.com/api/v1/orders/create \
  -H "X-API-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Key Types

Prefix	Environment	Purpose
`pk_live_`	Production	Live shipments with real carriers
`pk_test_`	Sandbox	Testing without creating real shipments

Never use production keys (pk_live_) for testing. Use sandbox keys (pk_test_) instead.

Getting Your API Key

Visit dashboard.crbtrack.com

Go to API Keys

Navigate to Settings → API Keys

Generate Key

Click Generate New Key and configure:

Name: A descriptive name (e.g., “Production Website”)
Countries: Which countries this key can ship to
IP Whitelist: Optional IP restrictions

Save Securely

The full key is shown only once. Save it immediately.

Key Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code.

# .env file (never commit this!)
CROSSBORDERLY_API_KEY=pk_your_production_key

// Access in code
const apiKey = process.env.CROSSBORDERLY_API_KEY;

Restrict by IP

In the dashboard, add your server’s IP addresses to the whitelist. Requests from other IPs will be rejected.

Rotate Keys Regularly

Generate new keys periodically and revoke old ones. This limits exposure if a key is compromised.

Never Expose Client-Side

API keys should only be used server-side. Never include them in:

Browser JavaScript
Mobile app bundles
Public repositories

Country Access Control

Each API key is restricted to specific destination countries. This is configured when generating the key.

Allowed Countries	What It Means
`EC, MX, CO`	Can create orders shipping to Ecuador, Mexico, Colombia
`*` (All)	Can ship to any supported country

If you try to create an order to a country not in your key’s whitelist:

{
  "success": false,
  "error": {
    "code": "AUTH_COUNTRY_NOT_ALLOWED",
    "message": "Your API key is not authorized to ship to BR",
    "message_es": "Su clave API no está autorizada para enviar a BR"
  }
}

Rate Limiting Headers

Every response includes rate limit information:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1703155200

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets

Error Responses

Invalid API Key

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "message_es": "La clave API proporcionada es inválida o ha sido revocada"
  }
}

HTTP Status: 401 Unauthorized

Missing API Key

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_API_KEY",
    "message": "API key is required. Include it in the X-API-Key header",
    "message_es": "Se requiere clave API. Inclúyala en el encabezado X-API-Key"
  }
}

HTTP Status: 401 Unauthorized

Rate Limit Exceeded

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please wait before retrying.",
    "message_es": "Demasiadas solicitudes. Por favor espere antes de reintentar.",
    "retryAfter": 30
  }
}

HTTP Status: 429 Too Many Requests

Testing Authentication

Use this endpoint to verify your API key is working:

curl https://api.crbtrack.com/api/v1/health \
  -H "X-API-Key: <YOUR_API_KEY>"

Successful response:

{
  "status": "ok",
  "authenticated": true,
  "keyName": "Production Website",
  "allowedCountries": ["EC", "MX", "CO"]
}

Getting Started

Reference

API Key Authentication

Key Types

Getting Your API Key

Key Security Best Practices

Country Access Control

Rate Limiting Headers

Error Responses

Invalid API Key

Missing API Key

Rate Limit Exceeded

Testing Authentication

​API Key Authentication

​Key Types

​Getting Your API Key

​Key Security Best Practices

​Country Access Control

​Rate Limiting Headers

​Error Responses

​Invalid API Key

​Missing API Key

​Rate Limit Exceeded

​Testing Authentication

API Key Authentication

Key Types

Getting Your API Key

Key Security Best Practices

Country Access Control

Rate Limiting Headers

Error Responses

Invalid API Key

Missing API Key

Rate Limit Exceeded

Testing Authentication