API Authentication

Overview

ZiaSign uses API key authentication with HMAC-SHA256 request signing. Every API request must include:

Your API Key ID in the X-Api-Key header
A timestamp in the X-Timestamp header (ISO 8601)
A signature in the X-Signature header (HMAC-SHA256)

Getting Your API Keys

Navigate to Dashboard → Developer APIs
Open the Credentials tab
Click Create API Key
Give your key a name, select scopes (permissions), and set an expiration date
Copy both the Key ID and Secret — the secret is only shown once

Important: Store your API secret securely. Never commit it to version control or expose it in client-side code. Key creation and rotation events are recorded in the audit trail.

Request Signing

Every request must include an HMAC-SHA256 signature computed from:

signature_payload = HTTP_METHOD + "\n" + URL_PATH + "\n" + TIMESTAMP + "\n" + BODY_SHA256

Where BODY_SHA256 is the SHA-256 hash of the request body (empty string hash for GET requests).

cURL Example

bash

# Set your credentials
API_KEY="your_api_key_id"
API_SECRET="your_api_secret"
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

# Compute the signature
BODY=""
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $2}')
PAYLOAD=$(printf 'GET\n/documents\n%s\n%s' "$TIMESTAMP" "$BODY_HASH")
SIGNATURE=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -hex | awk '{print $2}')

# Make the request
curl -X GET "https://api.ziasign.com/api/v1/documents" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Content-Type: application/json"

JavaScript / TypeScript

typescript

import crypto from "crypto";

const API_KEY = process.env.ZIASIGN_API_KEY!;
const API_SECRET = process.env.ZIASIGN_API_SECRET!;
const BASE_URL = "https://api.ziasign.com/api/v1";

async function ziasignFetch(method: string, path: string, body?: object) {
  const timestamp = new Date().toISOString();
  const bodyStr = body ? JSON.stringify(body) : "";
  const bodyHash = crypto.createHash("sha256").update(bodyStr).digest("hex");
  const payload = `${method}\n${path}\n${timestamp}\n${bodyHash}`;
  const signature = crypto
    .createHmac("sha256", API_SECRET)
    .update(payload)
    .digest("hex");

  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: {
      "X-Api-Key": API_KEY,
      "X-Timestamp": timestamp,
      "X-Signature": signature,
      "Content-Type": "application/json",
    },
    body: bodyStr || undefined,
  });

  if (!response.ok) throw new Error(`API error: ${response.status}`);
  return response.json();
}

// List documents
const docs = await ziasignFetch("GET", "/documents");

Python

python

import hashlib
import hmac
import json
import os
from datetime import datetime, timezone

import requests

API_KEY = os.environ["ZIASIGN_API_KEY"]
API_SECRET = os.environ["ZIASIGN_API_SECRET"]
BASE_URL = "https://api.ziasign.com/api/v1"


def ziasign_request(method: str, path: str, body: dict | None = None):
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
    body_str = json.dumps(body) if body else ""
    body_hash = hashlib.sha256(body_str.encode()).hexdigest()
    payload = f"{method}\n{path}\n{timestamp}\n{body_hash}"
    signature = hmac.new(
        API_SECRET.encode(), payload.encode(), hashlib.sha256
    ).hexdigest()

    response = requests.request(
        method,
        f"{BASE_URL}{path}",
        headers={
            "X-Api-Key": API_KEY,
            "X-Timestamp": timestamp,
            "X-Signature": signature,
            "Content-Type": "application/json",
        },
        data=body_str or None,
    )
    response.raise_for_status()
    return response.json()


# List documents
docs = ziasign_request("GET", "/documents")

C#

csharp

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

public class ZiaSignClient
{
    private readonly string _apiKey;
    private readonly string _apiSecret;
    private readonly HttpClient _http;
    private const string BaseUrl = "https://api.ziasign.com/api/v1";

    public ZiaSignClient(string apiKey, string apiSecret)
    {
        _apiKey = apiKey;
        _apiSecret = apiSecret;
        _http = new HttpClient { BaseAddress = new Uri(BaseUrl) };
    }

    public async Task<JsonDocument> RequestAsync(
        HttpMethod method, string path, object? body = null)
    {
        var timestamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");
        var bodyStr = body is not null ? JsonSerializer.Serialize(body) : "";
        var bodyHash = Convert.ToHexString(
            SHA256.HashData(Encoding.UTF8.GetBytes(bodyStr))).ToLower();
        var payload = $"{method.Method}\n{path}\n{timestamp}\n{bodyHash}";
        var signature = Convert.ToHexString(
            HMACSHA256.HashData(
                Encoding.UTF8.GetBytes(_apiSecret),
                Encoding.UTF8.GetBytes(payload))).ToLower();

        var request = new HttpRequestMessage(method, path);
        request.Headers.Add("X-Api-Key", _apiKey);
        request.Headers.Add("X-Timestamp", timestamp);
        request.Headers.Add("X-Signature", signature);

        if (body is not null)
            request.Content = new StringContent(
                bodyStr, Encoding.UTF8, "application/json");

        var response = await _http.SendAsync(request);
        response.EnsureSuccessStatusCode();
        var stream = await response.Content.ReadAsStreamAsync();
        return await JsonDocument.ParseAsync(stream);
    }
}

// Usage
var client = new ZiaSignClient("your_key", "your_secret");
var docs = await client.RequestAsync(HttpMethod.Get, "/documents");

Key Scopes

When creating an API key, select only the permissions your integration needs:

Scope	Access
`documents:read`	List and retrieve documents
`documents:write`	Create, send, void, and delete documents
`templates:read`	List and retrieve templates
`templates:write`	Create, update, and delete templates
`webhooks:manage`	Create and manage webhook subscriptions
`team:read`	List team members and roles

Rate Limits

API requests are rate-limited per key:

Plan	Rate Limit
Sandbox (Free)	60 requests/minute
Starter API	300 requests/minute
Growth API	1,000 requests/minute
Scale / Enterprise API	Custom (contact sales)

Rate limit headers are included in every response:

text

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1713200000

Frequently asked questions

Where do I find my API keys?

Go to Dashboard → Developer APIs → Credentials tab. You can create multiple keys with different scopes and expiration dates.

What is request signing?

Request signing uses HMAC-SHA256 to create a signature from your request details and secret key. This proves the request came from you and wasn't tampered with in transit.

Can I rotate my API keys without downtime?

Yes. Create a new key, update your application, then delete the old key. ZiaSign supports multiple active keys simultaneously.