DataZen Documentation
DataZen User Guide

Examples with X.509

These samples start a pipeline when a Service Token is configured to require an X.509 signature. The caller must have the signing certificate (with private key) available on the local machine. In addition to Authorization: Token …, each request must include:

  • https-Client-Certificate — the certificate thumbprint (SHA-1 hash) registered on the Service Token / agent.
  • X-API-DateTime — the current timestamp in UTC (ISO 8601 / round-trip format, for example 2026-10-15T13:45:01.1234567Z).
  • X-API-DateTimeHash — Base64 of an RSA PKCS#1 signature of the X-API-DateTime string (UTF-8 bytes), using SHA-1 and the certificate private key.

To be valid, X-API-DateTime must be calculated in UTC and must not be more than 5 minutes older than the server’s current time. Values in the future are rejected. Compute a fresh timestamp and signature on every request (signatures cannot be reused).

The base URL differs for every implementation: self-hosted — https://localhost:9550/; cloud — https://<ENVIRONMENT>.enzounified.com/api/<AGENT ID>/. For token-only samples without signing, see Examples. Certificate registration and signing requirements are covered under X.509 Certificates.

Raw HTTP

Structure of a signed request (similar to Fiddler). Replace the thumbprint and compute X-API-DateTime / X-API-DateTimeHash at call time — a static hash will not validate.

POST https://localhost:9550/job/start?guid=211161ac428447be80dc96fdde209b83 HTTP/1.1
User-Agent: Fiddler
Authorization: Token OWVhZTJiODE4MjlhNDc2OWJlOWU5MWQ3YmQyYmE3N2E=
https-Client-Certificate: A1B2C3D4E5F60718293A4B5C6D7E8F9012345678
X-API-DateTime: 2026-10-15T13:45:01.1234567Z
X-API-DateTimeHash: <Base64(RSA-SHA1 signature of X-API-DateTime)>

PowerShell

# Base URL differs by deployment:
#   self-hosted: https://localhost:9550/
#   cloud:       https://<ENVIRONMENT>.enzounified.com/api/<AGENT ID>/
$baseUrl    = "https://localhost:9550/"
$guid       = "211161ac428447be80dc96fdde209b83"
$token      = "OWVhZTJiODE4MjlhNDc2OWJlOWU5MWQ3YmQyYmE3N2E="
$thumbprint = "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678"

# Certificate with private key must be in the local My store
$cert = Get-Item "Cert:\CurrentUser\My\$thumbprint"
if (-not $cert) { $cert = Get-Item "Cert:\LocalMachine\My\$thumbprint" }

$datetime = [DateTime]::UtcNow.ToString("o")
$bytes    = [Text.Encoding]::UTF8.GetBytes($datetime)
$rsa      = [System.Security.Cryptography.X509Certificates.RSACertificateExtensions]::GetRSAPrivateKey($cert)
$hash     = [Convert]::ToBase64String(
    $rsa.SignData(
        $bytes,
        [Security.Cryptography.HashAlgorithmName]::SHA1,
        [Security.Cryptography.RSASignaturePadding]::Pkcs1))

Invoke-RestMethod -Method Post `
  -Uri ($baseUrl.TrimEnd('/') + "/job/start?guid=$guid") `
  -Headers @{
    Authorization                 = "Token $token"
    "https-Client-Certificate"    = $thumbprint
    "X-API-DateTime"              = $datetime
    "X-API-DateTimeHash"          = $hash
  }

Python

This sample loads a local PFX that contains the signing certificate and private key (export the certificate from the machine store if needed). Install requests and cryptography.

import base64
from datetime import datetime, timezone

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

# Base URL differs by deployment:
#   self-hosted: https://localhost:9550/
#   cloud:       https://<ENVIRONMENT>.enzounified.com/api/<AGENT ID>/
base_url = "https://localhost:9550/"
guid = "211161ac428447be80dc96fdde209b83"
token = "OWVhZTJiODE4MjlhNDc2OWJlOWU5MWQ3YmQyYmE3N2E="
thumbprint = "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678"
pfx_path = r"C:\certs\datazen-signing.pfx"
pfx_password = None  # or b"your-pfx-password"

with open(pfx_path, "rb") as f:
    private_key, cert, _ = pkcs12.load_key_and_certificates(f.read(), pfx_password)

datetime_utc = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
signature = private_key.sign(
    datetime_utc.encode("utf-8"),
    padding.PKCS1v15(),
    hashes.SHA1(),
)
datetime_hash = base64.b64encode(signature).decode("ascii")

resp = requests.post(
    f"{base_url.rstrip('/')}/job/start",
    params={"guid": guid},
    headers={
        "Authorization": f"Token {token}",
        "https-Client-Certificate": thumbprint,
        "X-API-DateTime": datetime_utc,
        "X-API-DateTimeHash": datetime_hash,
    },
)
resp.raise_for_status()
print(resp.text)

C#

using System.Net.Http;
using System.Security.Cryptography;
using System.Security.Cryptography.X509Certificates;
using System.Text;

// Base URL differs by deployment:
//   self-hosted: https://localhost:9550/
//   cloud:       https://<ENVIRONMENT>.enzounified.com/api/<AGENT ID>/
var baseUrl = "https://localhost:9550/";
var guid = "211161ac428447be80dc96fdde209b83";
var token = "OWVhZTJiODE4MjlhNDc2OWJlOWU5MWQ3YmQyYmE3N2E=";
var thumbprint = "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678";

X509Certificate2 FindCert(StoreLocation location)
{
    using var store = new X509Store(StoreName.My, location);
    store.Open(OpenFlags.ReadOnly);
    var found = store.Certificates.Find(X509FindType.FindByThumbprint, thumbprint, false);
    return found.Count > 0 ? found[0] : null;
}

var cert = FindCert(StoreLocation.CurrentUser) ?? FindCert(StoreLocation.LocalMachine)
    ?? throw new InvalidOperationException("Certificate not found in the local My store.");

var datetime = DateTime.UtcNow.ToString("o");
var signature = cert.GetRSAPrivateKey()!.SignData(
    Encoding.UTF8.GetBytes(datetime),
    HashAlgorithmName.SHA1,
    RSASignaturePadding.Pkcs1);
var datetimeHash = Convert.ToBase64String(signature);

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Post,
    $"{baseUrl.TrimEnd('/')}/job/start?guid={guid}");
request.Headers.TryAddWithoutValidation("Authorization", "Token " + token);
request.Headers.TryAddWithoutValidation("https-Client-Certificate", thumbprint);
request.Headers.TryAddWithoutValidation("X-API-DateTime", datetime);
request.Headers.TryAddWithoutValidation("X-API-DateTimeHash", datetimeHash);

using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Related Topics