Skip to main content

​
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: pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

​
Key Types

PrefixEnvironmentPurpose
pk_live_ProductionLive shipments with real carriers
pk_test_SandboxTesting without creating real shipments
Never use production keys (pk_live_) for testing. Use sandbox keys (pk_test_) instead.

​
Getting Your API Key

1

Login to Dashboard

Visit dashboard.crbtrack.com
2

Go to API Keys

Navigate to Settings → API Keys
3

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
4

Save Securely

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

​
Key Security Best Practices

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;
In the dashboard, add your server’s IP addresses to the whitelist. Requests from other IPs will be rejected.
Generate new keys periodically and revoke old ones. This limits exposure if a key is compromised.
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 CountriesWhat It Means
EC, MX, COCan 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
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix 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: pk_your_api_key"
Successful response: 
{
  "status": "ok",
  "authenticated": true,
  "keyName": "Production Website",
  "allowedCountries": ["EC", "MX", "CO"]
}