How to Sign Your API Requests

ActionStreamer uses HMAC SHA256 authentication for its API endpoints. You can either sign requests yourself or use the Python SDK, which handles signing for you when you pass in your access key and secret key.

This tutorial shows the signing flow in a way you can apply to every authenticated request.

What You Need

• An ActionStreamer API key

• An ActionStreamer secret key

• The HTTP method for the request

• The request path

• Any request headers that belong in the signature

• Any query parameters that belong in the signature

• The request body, if the request has one

The Signing Model

The signature is built from a single canonical string. That string should include the request method, the normalized path, the relevant headers, the relevant parameters, and the body if one is present.

The important part is consistency:

• Use the same method you will send over HTTP.

• Normalize the path before signing it.

• Sort any header or parameter keys the same way every time.

• Include the body exactly as it will be sent.

If any part of the request changes, the signature changes too.

Canonical Request Shape

The request data should be assembled in a predictable order before signing.

1. Start with the HTTP method.

2. Normalize the path so it begins with / and does not end with a trailing slash unless it is the root path.

3. Include the headers that belong in the signature.

4. Include the query parameters that belong in the signature.

5. Include the body text if the request has a body.

The result is a canonical string that can be passed into HMAC SHA256 with the secret key.

Example Python Implementation

import hashlib
import hmac


def build_dictionary_string(values):
    lines = []
    for key in sorted(values.keys()):
        lines.append(f"{key}: {values[key]}")
    return "\n".join(lines)


def normalize_path(path):
    if not path.startswith("/"):
        path = "/" + path
    if path.endswith("/") and len(path) > 1:
        path = path[:-1]
    return path


def build_string_to_sign(method, path, headers, parameters, body=None):
    header_string = build_dictionary_string(headers)
    parameter_string = build_dictionary_string(parameters)
    normalized_path = normalize_path(path)
    body_string = body if body else ""
    return "\n".join([method, normalized_path, header_string, parameter_string, body_string]

Using The Python SDK Instead

If you do not want to sign raw HTTP requests yourself, the Python SDK can do that work for you.

The basic pattern is:

1. Load your access key and secret key.

2. Build the SDK config object with those credentials.

3. Call the wrapped API function instead of building the HTTP request manually.

Example:

The wrapper handles the request signing internally, so you do not have to build the HMAC signature in your own code when you use the SDK.

How To Use The Signature

Once you generate the signature, send it with the rest of the request authentication data required by the API. The exact header names and request format should match the current documentation for the endpoint you are calling.

The key point is that the server must be able to reconstruct the same canonical request you signed locally.

Common Mistakes

• Signing a path that does not match the actual HTTP request path

• Forgetting to normalize the leading or trailing slash

• Changing header order between signing and sending

• Leaving a query parameter out of the string to sign

• Signing a body that is different from the body actually sent

• Depending on wrapper behavior without checking the current SDK version

When To Use Python

Use raw HTTP first when you are learning the API contract or when you want full control over request construction.

Use the Python SDK when you want the wrapper to handle signing and you are comfortable relying on the current package version.

What Comes Next

The next post covers registering a device and sending its first heartbeat. Once signing is working, that workflow becomes the first real end-to-end test of your integration.