Authentication

How to authenticate API requests

Authentication

WhereParcel API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard.

Getting Your API Key

1. Sign in to your WhereParcel account
2. Navigate to Dashboard → API Keys
3. Click Generate New API Key
4. Save your API key and secret key securely

:::warning ⚠️ Important: Save your secret key securely. You won’t be able to see it again! :::

Request Headers

All API requests must include the following headers:

Example with cURL

curl -X POST https://api.whereparcel.com/v2/track \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingItems": [
      {
        "carrier": "us.usps",
        "trackingNumber": "9400111899562537866361"
      }
    ]
  }'

Example with Node.js

const response = await fetch('https://api.whereparcel.com/v2/track', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    trackingItems: [
      {
        carrier: 'us.usps',
        trackingNumber: '9400111899562537866361'
      }
    ]
  })
});

const data = await response.json();

Using Environment Variables

Store your API keys in environment variables to avoid committing them to version control:

# .env file
WHEREPARCEL_API_KEY=your_api_key_here
WHEREPARCEL_SECRET_KEY=your_secret_key_here

:::tip 💡 Tip: Add .env to your .gitignore file to prevent accidentally committing sensitive credentials. :::

Security Best Practices

• Never share your API keys publicly
• Store keys in environment variables
• Use different keys for development and production
• Rotate keys regularly
• Revoke compromised keys immediately

Authentication Error Responses

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key or secret key"
  }
}