WhereParcel Authentication: API Key & Signature Methods (2026)

Authentication overview

WhereParcel's API utilizes a combination of API keys and request signatures to authenticate incoming requests. This dual-component approach ensures that requests originate from a legitimate source and have not been tampered with during transit. The API key identifies the client, while the signature verifies the integrity and authenticity of the request's content. This method aligns with common security practices for RESTful APIs, providing a robust layer of protection for sensitive logistics data.

Access to the WhereParcel API requires valid credentials, which are managed within the WhereParcel dashboard. Developers can generate and revoke API keys and secret keys as needed, following a lifecycle management approach to security. WhereParcel's API reference documentation provides detailed instructions on how to implement authentication across various programming languages and frameworks, catering to the supported SDKs including Node.js, PHP, and Python.

Supported authentication methods

WhereParcel primarily supports an API Key with a request signature for authenticating API calls. This method involves sending a unique API key with each request to identify your application and a cryptographic signature to verify the request's integrity.

The API Key + Request Signature method is based on a shared secret model. Your unique API Key is sent as part of the request, typically in a header. A signature is then computed using a secret key and relevant parts of the request (like the timestamp, request body, and method) with a hashing algorithm like HMAC-SHA256. This signature is also included in the request. The WhereParcel server then re-computes the signature using its copy of your secret key and compares it to the one sent. If they match, the request is authenticated and processed.

This approach helps protect against replay attacks and ensures that the request's payload has not been altered in transit. For further reading on the principles of request signing and HMAC, the IETF's RFC 2104 details the HMAC message authentication code.

Getting your credentials

To begin authenticating with the WhereParcel API, you first need to obtain your API key and secret key. These credentials are generated and managed within your WhereParcel account dashboard.

1. Sign Up or Log In: Navigate to the WhereParcel website and either sign up for a new account or log in to your existing one. Even the free tier includes 50 shipments/month and provides API access.
2. Access API Settings: Once logged in, locate the "API Settings" or "Developers" section in your dashboard. The exact navigation may vary, but it's typically found under account settings or a dedicated developer portal.
3. Generate API Key: Within the API settings, you will find an option to generate a new API key. This key is a public identifier for your application.
4. Generate Secret Key: Alongside the API key, you will also need to generate a secret key. This key is a cryptographic secret, used in conjunction with your API key to sign requests. It should be treated with the highest level of confidentiality.
5. Store Securely: Once generated, safely store both your API key and secret key. The secret key is often shown only once upon generation; if lost, you may need to revoke it and generate a new one.

WhereParcel's dashboard allows you to manage multiple API keys, enabling you to create separate keys for different environments (e.g., development, staging, production) or for different applications you integrate with WhereParcel. This practice enhances security by limiting the scope of compromise should one key be exposed.

Authenticated request example

This example demonstrates how to construct an authenticated request using Python, employing the API key and secret key for signing. The general principles apply across other supported SDKs like Node.js and PHP.

import hashlib
import hmac
import json
import time
import requests

# Your WhereParcel Credentials
API_KEY = "YOUR_WHEREPARCEL_API_KEY"
SECRET_KEY = "YOUR_WHEREPARCEL_SECRET_KEY".encode('utf-8') # Encode secret key for HMAC

# API Endpoint and Request Data
API_BASE_URL = "https://api.whereparcel.com/v1"
TRACKING_ENDPOINT = f"{API_BASE_URL}/trackings"

request_body = {
    "tracking_number": "LPXXXXXXXXXXXXX",
    "carrier_code": "usps"
}

def create_signature(method, url_path, body, timestamp, secret_key):
    # Sort body keys for consistent serialization
    sorted_body_str = json.dumps(body, sort_keys=True, separators=(',', ':')) if body else ""

    # Concatenate parts to sign
    string_to_sign = f"{method.upper()}\n{url_path}\n{sorted_body_str}\n{timestamp}"

    # Create HMAC-SHA256 signature
    hashed = hmac.new(secret_key, string_to_sign.encode('utf-8'), hashlib.sha256)
    return hashed.hexdigest()

# --- Make the authenticated request ---
method = "POST"
url_path = "/v1/trackings" # Path without base URL
timestamp = str(int(time.time()))

signature = create_signature(method, url_path, request_body, timestamp, SECRET_KEY)

headers = {
    "Content-Type": "application/json",
    "X-WP-API-Key": API_KEY,
    "X-WP-Timestamp": timestamp,
    "X-WP-Signature": signature
}

try:
    response = requests.post(TRACKING_ENDPOINT, headers=headers, json=request_body)
    response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx)
    print("Request successful:")
    print(json.dumps(response.json(), indent=2))
except requests.exceptions.HTTPError as err:
    print(f"HTTP error occurred: {err}")
    print(response.json())
except Exception as err:
    print(f"An error occurred: {err}")

In this example, the create_signature function generates a unique hash based on the HTTP method, the request path, the JSON request body (sorted for consistency), and a Unix timestamp. These components, along with your secret key, form the basis for the HMAC-SHA256 signature. The generated signature, API key, and timestamp are then included in specific HTTP headers (X-WP-API-Key, X-WP-Timestamp, X-WP-Signature) when making the POST request to the /v1/trackings endpoint. The WhereParcel API documentation provides further language-specific examples and details on endpoint paths.

Security best practices

Implementing strong security practices is critical when integrating with any API, especially when handling sensitive logistics data. Adhering to these guidelines will help protect your WhereParcel integration from common vulnerabilities:

• Protect Your Secret Key: Your secret key is highly sensitive. Never hardcode it directly into client-side code (e.g., JavaScript in a browser). For server-side applications, store it as an environment variable or in a secure configuration management system, not directly in your source code repository. Implementations like AWS Secrets Manager or Azure Key Vault provide secure storage solutions for API keys and other credentials.
• Rotate Keys Regularly: Periodically rotate your API and secret keys. This practice minimizes the window of exposure if a key is compromised. Most platforms, including WhereParcel, provide mechanisms in their dashboards to revoke old keys and generate new ones without service interruption.
• Use HTTPS/TLS: Always ensure all communications with the WhereParcel API occur over HTTPS (TLS). This encrypts data in transit, preventing eavesdropping and tampering. WhereParcel API endpoints are exclusively served over HTTPS.
• Validate Webhook Signatures: If you are using WhereParcel webhooks for real-time updates, always verify the signature included with each webhook payload. WhereParcel sends a signature header (e.g., X-WP-Webhook-Signature) similar to how API requests are signed. This verifies that the webhook originated from WhereParcel and that its content hasn't been altered.
• Implement Least Privilege: If WhereParcel introduces role-based access control (RBAC) for API keys in the future, generate keys with only the necessary permissions for the tasks they perform. Avoid using a single key with full access for all operations.
• Monitor API Usage: Regularly monitor your API usage logs for any unusual activity or spikes in requests that could indicate unauthorized access. Set up alerts for failed authentication attempts.
• Error Handling: Implement robust error handling for authentication failures. Avoid providing overly descriptive error messages that could aid an attacker. A generic "Authentication failed" is generally preferred over "Invalid API Key" or "Signature mismatch."
• Sanitize Inputs: Ensure all inputs sent to the API are properly sanitized to prevent injection attacks, even if the API itself has internal protections.
• Secure Development Lifecycle: Integrate security considerations throughout your software development lifecycle. Conduct regular security audits and penetration testing on your applications that integrate with WhereParcel.