Skip to main content

Overview

All requests to the EASYCRED Partner API require an API key and an HMAC-SHA256 Signature. This ensures every API transaction is authenticated, tamper-proof, and protected against replay attacks.

Required Request Headers

Every call must include these four signature headers:
Headless Journeys: On subsequent calls after initiating a headless journey (polling state, submitting actions, signaling return), also include the X-Journey-Session header with your journey token.

Canonical Signing String

Generate the length-prefixed canonical string below, sign it with your signingSecret using HMAC-SHA256, and hex-encode the result:

Components

  • METHOD: Uppercase HTTP verb (POST or GET).
  • PATH: Exact requested path without query parameters (e.g. /v1/partner/journey/initiate or /api/v1/partner/products).
  • TIMESTAMP: String value passed in x-timestamp.
  • NONCE: String value passed in x-nonce.
  • BODY: Raw JSON string payload. For GET requests (or any request without a payload body), the body has 0 characters, meaning the canonical string ends with the trailing colon : followed by nothing (e.g. v1:3:GET:...:<nonce>:). Do not append literal quotation mark characters ("").
Exact Path Matching: The PATH component in your HMAC string must match the exact path in your HTTP request. If you call /v1/partner/journey/initiate, sign /v1/partner/journey/initiate. If you call /api/v1/partner/products, sign /api/v1/partner/products.

Security Windows

  • Timestamp Drift: Server validates timestamps within a ±300 second (5-minute) window. Ensure server clocks are synchronized via NTP.
  • Nonce Replay: Each nonce is single-use. Replays within the validation window are rejected with 401 Unauthorized.

Implementation Examples

Use the tabs below to view end-to-end request signing and API invocation in your language of choice: