Server-to-Server (REST API) Integration

If you are providing custom interfaces (such as an in-app contract screen or a fully custom web consent experience), you can obtain legal consent on your own Backend servers and securely transmit it to HashEntry’s Consent Log system Backend-to-Backend.

Authentication

API requests must include the X-API-Key HTTP header with your unique Site’s API key from the HashEntry dashboard.

HMAC Request Signing

All POST requests must be signed with HMAC-SHA256 to ensure request integrity and replay protection. The JS SDK handles this automatically; for server-side integrations you must implement signing manually.

Required Headers

Header	Description
X-API-Key	Your Site API key
X-Signature	HMAC-SHA256 signature of the canonical request
X-Timestamp	Unix timestamp (seconds) — must be within ±300s of server time
X-Nonce	Unique UUID per request — prevents replay attacks

Signing Algorithm

1. timestamp = current Unix timestamp (seconds)
2. nonce = random UUID
3. bodyHash = SHA-256(request body JSON string)
4. canonical = "{METHOD}\n{PATH}\n{timestamp}\n{nonce}\n{bodyHash}"
5. signature = HMAC-SHA256(canonical, apiKey)

Example (Node.js)

const crypto = require('crypto');

const apiKey = 'he_live_xxx';
const body = JSON.stringify({ consent_type: 'cookie_consent', decision: 'accept', ... });
const timestamp = Math.floor(Date.now() / 1000).toString();
const nonce = crypto.randomUUID();
const bodyHash = crypto.createHash('sha256').update(body).digest('hex');

const canonical = `POST\n/tool/v1/consents\n${timestamp}\n${nonce}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', apiKey).update(canonical).digest('hex');

// Headers:
// X-API-Key: he_live_xxx
// X-Signature: {signature}
// X-Timestamp: {timestamp}
// X-Nonce: {nonce}

S2S Authentication (Server-to-Server)

For automated backend integrations, you can use the S2S Auth flow which combines API key authentication with JWT Bearer tokens for enhanced security.

How It Works

1. Create an api_user role member via the HashEntry Dashboard (Settings → Team → Invite)
2. The API user logs in via POST /api/v1/auth/login to obtain a JWT token
3. Include both headers in S2S requests:

X-API-Key: he_live_xxx
Authorization: Bearer {jwt_token}

S2S Endpoints

Method	Endpoint	Description
POST	/tool/v1/s2s/consents	Record a single consent
POST	/tool/v1/s2s/consents/batch	Record batch consents
GET	/tool/v1/s2s/consents/export	Export consent records

Note: The api_user role is restricted to S2S API access only — panel login is not permitted for this role.

Recording Consent

It is used to permanently and immutably record actions (cookie consent, contract approval, etc.) defined by the user in your system.

Endpoint: POST https://system.hashentry.com/tool/v1/consents

Required Headers:

Content-Type: application/json
X-API-Key: YOUR_SITE_API_KEY
X-Signature: {hmac_signature}
X-Timestamp: {unix_timestamp}
X-Nonce: {unique_uuid}

Scenario 1: Custom Cookie Consent Request (JSON)

If you extracted cookie permissions from your native UI:

{
  "consent_type": "cookie_consent",
  "decision": "accept",
  "document_version_id": "cookie-policy-version-uuid",
  "visitor_region": "us",
  "compliance_framework": "ccpa",
  "metadata": {
    "categories": {
      "necessary": true,
      "analytics": true,
      "marketing": false
    }
  }
}

Scenario 2: Document Approval Request (JSON)

Example of a user accepting the Distance Sales Contract before placing an order:

{
  "consent_type": "document_approval",
  "decision": "accept",
  "document_version_id": "terms-of-service-version-uuid",
  "ip_address": "192.168.1.5",
  "user_agent": "Mozilla/5.0 ...",
  "metadata": {
    "order_id": "ORD-54321",
    "customer_no": "CUST-999"
  }
}

Successful Response (201 Created)

{
  "message": "Consent recorded",
  "data": {
    "consent_token": "ct_1234abc...",
    "proof_hash": "sha256:abcd12...",
    "created_at": "2026-03-27T14:00:00+03:00"
  }
}

The returned proof_hash acts as irrefutable cryptographic evidence of the legal consent action.

Advanced Features

• Batch Transfers: Submit batched consents via POST /tool/v1/consents/batch to reduce network loads.
• Active Document Query: Continuously query GET /tool/v1/documents/{slug}/active to keep contract texts updated in real-time.