Ensuring the security of your data and our services is paramount. This section details the authentication and authorization mechanisms required to interact with our API.Authentication#
Authentication to our API is managed via an API Key. You must include your unique API Key in the header of every request.To ensure maximum security and verify the integrity of each request, all API calls must also be signed. This signature is generated using your API Secret with the HMAC SHA-256 algorithm.The following headers must be included in every API request:| Name | Description |
|---|
x-api-key | Your unique API key. |
x-signature | The generated HMAC SHA-256 signature for the request. |
x-timestamp | A Unix timestamp (seconds since epoch) indicating when the request was made. This helps prevent replay attacks. |
x-endpoint | The request path (e.g., /users, /account). |
x-org-id | Your organization's unique identifier. |
Why This Authentication Method is Secure#
The security of our API authentication, leveraging API Keys combined with HMAC SHA-256 signed requests, provides a robust defense against common web security threats. Here's why this approach is highly secure:1.
Integrity Verification (Anti-Tampering):
The HMAC SHA-256 signature ensures that the request (including the endpoint, timestamp, and body) has not been altered in transit. If even a single character of the signed data is changed, the signature calculated by the server will not match the one you sent. This immediately flags the request as potentially compromised.
2.
Authenticity (Proof of Origin):
Because the signature is generated using a API_SECRET known only to you and the server, a valid signature proves that the request originated from an authorized source possessing this secret. It's computationally infeasible for an attacker to guess or forge a valid signature without knowing the secret key.
3.
Protection Against Replay Attacks:
The inclusion of a x-timestamp in the signed data is crucial. Our servers can validate this timestamp to ensure the request is recent, rejecting old or replayed requests. This significantly mitigates the risk of an attacker capturing a valid request and resending it later. (It's important that the server implements a narrow window for acceptable timestamps).
4.
Secret Key Confidentiality:
The actual API_SECRET is never transmitted over the network. Only the resulting signature is sent. This means that even if a request is intercepted, the secret key itself is not exposed, preventing attackers from being able to sign future malicious requests.
5.
Strong Cryptographic Algorithm:
SHA-256 is a widely recognized and strong cryptographic hash function. When combined with HMAC (Hash-based Message Authentication Code), it creates a message authentication code that is resistant to known cryptographic attacks, including collision attacks and pre-image attacks.
The cornerstone of this security model is the confidentiality of your API_SECRET. It is imperative that you treat your API_SECRET with the same level of security as you would any password or private key. Store it securely, never embed it directly in client-side code, and restrict access to it within your systems.
Generating the Signature#
To ensure the authenticity and integrity of your requests, a signature must be generated and included in the x-signature header. The signature is an HMAC SHA-256 hash created from the timestamp, the request path, and the request body (if present), using your API Secret.Think of generating the signature as creating a unique, tamper-proof seal for your API request. Here’s how it works step-by-step:1
Gather Your Ingredients
Your Secret Key (API_SECRET): This is like your private, unique stamp. Only you and the API server know it. It's crucial to keep this secret safe.
Timestamp (timestamp): The exact time you're sending the request. This prevents someone from intercepting your request and sending it again later.
Request Path (path): The specific API endpoint you're trying to access (e.g., /v1/users, /v1/products/42). This ensures the signature is valid only for this particular endpoint.
Request Body (content): The actual data you're sending (e.g., the JSON payload for creating a new user). If you're not sending any data (like in a GET request), this part will be empty, but it's still part of the process.
2
Prepare the Message to Sign
You'll combine the timestamp, request path, and request body content in a specific order. Imagine writing these down one after another on a piece of paper:
First, write down the timestamp.
Next, write down the path.
Finally, write down the content of your request body.
3
Apply the Secret Stamp (HMAC SHA-256)
Using your API_SECRET and the HMAC SHA-256 algorithm (a cryptographic hashing function), you'll process the combined "message" (timestamp + path + content).
This process transforms your message and secret key into a fixed-size string of characters. This string is the raw hash.
4
Encode for Readability (Base64)
The raw hash is often a series of bytes not easily representable as text. So, you'll convert this hash into a Base64 encoded string. This makes it easy to include in an HTTP header. This Base64 string is your final signature.
5
Attach the Signature
You'll add this Base64 signature to your request in the x-signature header, prefixed with hmac-sha256 (e.g., hmac-sha256 YOUR_GENERATED_BASE64_SIGNATURE).
Authenticity: The request genuinely came from you (because only you know the API_SECRET).
Integrity: The request content (path, body, timestamp) hasn't been altered in transit (because any change would result in a different signature).
This process ensures that your communication with the API is secure and trustworthy.
Here's an example of a Postman pre-request script that demonstrates how to generate the required signature. This script assumes you have your
API_SECRET stored as a Postman environment variable.
