Authentication and Security

Security controls on partner mutation endpoints

The following endpoints require all controls:

• POST /transactions/checkout-intent (recommended for all new integrations)
• POST /transactions/initialize (legacy 2-step flow only)
• POST /transactions/attach-intent (legacy 2-step flow only)
• POST /clients (register a merchant under your partner; partner-scoped API key only)

Controls:

1. x-api-key
2. x-clive-hmac
3. idempotency-key
4. partner rate limiting

Header reference

Header	Required	Description
x-api-key	Yes	Shared API key for partner authentication
x-clive-hmac	Yes	SHA-256 HMAC signature of exact request body
idempotency-key	Yes	Unique key to make retries safe and replayable
Content-Type	Yes	Use application/json

HMAC signing details

• Algorithm: HMAC-SHA256
• Message: exact raw JSON string body
• Secret: shared HMAC secret configured with Clive
• Output: lowercase hex digest

Node example

import crypto from "crypto";

function cliveSign(body: string, secret: string) {
  return crypto.createHmac("sha256", secret).update(body).digest("hex");
}

cURL example

BODY='{"partner_id":"ECHEZONA001","client_id":"AIRPEACE001","amount":750,"currency":"USD","email":"buyer@example.com","echezona_reference":"EZ12345","statement_descriptor_suffix":"AIRPEACE"}'
SIG=$(node -e "const c=require('crypto');console.log(c.createHmac('sha256', process.env.CLIVE_HMAC_SECRET).update(process.argv[1]).digest('hex'))" "$BODY")

curl -X POST "$CLIVE_API_BASE_URL/transactions/checkout-intent" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $CLIVE_API_KEY" \
  -H "x-clive-hmac: $SIG" \
  -H "idempotency-key: checkout-EZ12345-v1" \
  -d "$BODY"

Idempotency behavior

• If a prior response exists for the same key, Clive returns cached response.
• Replay responses include:

{
  "idempotentReplay": true
}

• Recommended key strategy:
  • checkout-{partnerRef}
  • legacy 2-step only: init-{partnerRef} then attach-{cliveTxId}

Common auth/security errors

HTTP	Code	Meaning
401	API_KEY_MISSING	x-api-key header missing
401	API_KEY_INVALID	API key mismatch
401	HMAC_MISSING	HMAC header missing
401	HMAC_INVALID	HMAC mismatch
400	IDEMPOTENCY_KEY_MISSING	No idempotency key
429	n/a	Rate limit exceeded
403	API_KEY_SCOPE_FORBIDDEN	Key has no partner scope (for example partner-only routes like /clients)