Skip to main content

Secure API Key Usage Guide

Introduction​

tip

Authentication has the signing rules in one place, a reusable helper that signs any request (with query string and body), and a checklist for 401 errors.

Let's effectively learn what's needed to use API Keys in practice. We'll use Python as it's simple and easy to demonstrate the necessary implementation.

Essential Request Components​

  1. API Key - Your previously registered API Key
  2. Timestamp - Current timestamp
  3. Base Endpoint - The API main domain (e.g. https://api.sandbox.avenia.io:10952)
  4. HTTP Method - The verb defining the action (GET, POST, PUT, PATCH, DELETE)
  5. Request URI - The specific path after the base endpoint (e.g. /v2/auth/api-keys)
  6. Request Body (when applicable) - Data to be sent in JSON format

Initial Setup​

First, we'll import the necessary libraries for cryptography and making requests:

Python
import time
import base64
import requests

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

api_key = "00000000-0000-0000-0000-000000000000"
endpoint = "https://api.sandbox.avenia.io:10952/v2/account/account-info"
method = "GET"
request_uri = "/v2/account/account-info"
body = ""
timestamp = str(int(time.time() * 1000))

string_to_sign = timestamp + method + request_uri # + body if the request contains a body
info

string_to_sign is what the signature will actually consist of. Remember that if the request you're making has a body, this field must also be included.

request_uri If your request has parameters or the URI changes, it must also be included in the request_uri. For example:

Shell
/v2/account/account-info?foo=bar

Loading the Private Key​

Next, we need to load the private_key.pem file that should be in the same directory as the Python file, and serialize it as an actual private key using our cryptography library:

Python
with open("private_key.pem", "rb") as key_file:
private_key = serialization.load_pem_private_key(
key_file.read(),
password=None,
)

Creating the Request Signature​

Now we'll build the request signature and return it as base64, using our private key:

Python
signature = private_key.sign(
string_to_sign.encode("utf-8"),
padding.PKCS1v15(),
hashes.SHA256()
)
signature_base64 = base64.b64encode(signature).decode("utf-8")

Building the Request​

Finally, we'll construct the request headers which consist of:

  1. X-API-KEY - Your previously registered API Key
  2. X-API-Timestamp - Current timestamp
  3. X-API-Signature - The signature we created earlier in base64
Python
print("Headers:")
print("X-API-Key:", api_key)
print("X-API-Timestamp:", timestamp)
print("X-API-Signature:", signature_base64)

headers = {
"X-API-Key": api_key,
"X-API-Timestamp": timestamp,
"X-API-Signature": signature_base64,
}

response = requests.get(endpoint, headers=headers)

print("Status:", response.status_code)
print("Response:", response.text)

Expected Output​

When running the complete code, you should see something like this:

Shell
Headers:
X-API-Key: 00000000-0000-0000-0000-000000000000
X-API-Timestamp: 1743107780606
X-API-Signature: eEnHoz2CWyMqFA/rx518ZF+y...

Status: 200
Response: {"id":"11111111-1111-1111-1111-111111111111" ... "createdAt":"2025-02-07T19:54:17.727744Z"}

Complete Code​

Here's the complete Python code for reference:

Python
import time
import base64
import requests

from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

# Configuration
api_key = "00000000-0000-0000-0000-000000000000"
endpoint = "https://api.sandbox.avenia.io:10952/v2/account/account-info"
method = "GET"
request_uri = "/v2/account/account-info"
body = ""
timestamp = str(int(time.time() * 1000))

# Create string to sign
string_to_sign = timestamp + method + request_uri # + body if the request contains a body

# Load private key
with open("private_key.pem", "rb") as key_file:
private_key = serialization.load_pem_private_key(
key_file.read(),
password=None,
)

# Generate signature
signature = private_key.sign(
string_to_sign.encode("utf-8"),
padding.PKCS1v15(),
hashes.SHA256()
)
signature_base64 = base64.b64encode(signature).decode("utf-8")

# Prepare headers
headers = {
"X-API-Key": api_key,
"X-API-Timestamp": timestamp,
"X-API-Signature": signature_base64,
}

# Make the request
response = requests.get(endpoint, headers=headers)

# Print results
print("Status:", response.status_code)
print("Response:", response.text)