Agency Signature

The Client API requires an agency signature header for multi-tenant context.

Format

X-Agency-Signature: {base64_payload}.{hmac_hash}

Payload Structure

{
  "agency_id": 123,
  "agency_code": "AGENCY123",
  "partner_id": 456,
  "timestamp": 1640995200
}

Signature Generation

1. JSON encode the payload
2. Base64 encode the JSON
3. HMAC-SHA256 sign with agency secret key
4. Combine: {base64}.{hmac}

PHP Example

$payload = [
    'agency_id' => 123,
    'agency_code' => 'AGENCY123',
    'partner_id' => 456,
    'timestamp' => time()
];

$json = json_encode($payload);
$base64 = base64_encode($json);
$hash = hash_hmac('sha256', $base64, $secretKey);

$signature = "$base64.$hash";

JavaScript Example

const crypto = require('crypto');

const payload = {
  agency_id: 123,
  agency_code: 'AGENCY123',
  partner_id: 456,
  timestamp: Math.floor(Date.now() / 1000)
};

const json = JSON.stringify(payload);
const base64 = Buffer.from(json).toString('base64');
const hash = crypto.createHmac('sha256', secretKey).update(base64).digest('hex');

const signature = `${base64}.${hash}`;

Swift Example

import CryptoKit
import Foundation

func generateSignature(agencyId: Int, agencyCode: String, partnerId: Int, secretKey: String) -> String {
    let payload: [String: Any] = [
        "agency_id": agencyId,
        "agency_code": agencyCode,
        "partner_id": partnerId,
        "timestamp": Int(Date().timeIntervalSince1970)
    ]

    let jsonData = try! JSONSerialization.data(withJSONObject: payload)
    let base64 = jsonData.base64EncodedString()

    let key = SymmetricKey(data: secretKey.data(using: .utf8)!)
    let signature = HMAC<SHA256>.authenticationCode(for: base64.data(using: .utf8)!, using: key)
    let hash = signature.map { String(format: "%02x", $0) }.joined()

    return "\(base64).\(hash)"
}

Kotlin Example

import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import android.util.Base64
import org.json.JSONObject

fun generateSignature(
    agencyId: Int,
    agencyCode: String,
    partnerId: Int,
    secretKey: String
): String {
    val payload = JSONObject().apply {
        put("agency_id", agencyId)
        put("agency_code", agencyCode)
        put("partner_id", partnerId)
        put("timestamp", System.currentTimeMillis() / 1000)
    }

    val json = payload.toString()
    val base64 = Base64.encodeToString(json.toByteArray(), Base64.NO_WRAP)

    val mac = Mac.getInstance("HmacSHA256")
    mac.init(SecretKeySpec(secretKey.toByteArray(), "HmacSHA256"))
    val hash = mac.doFinal(base64.toByteArray()).joinToString("") { "%02x".format(it) }

    return "$base64.$hash"
}

Validity

Signatures are valid for 24 hours from the timestamp.

Error Responses

Missing Signature

{
  "success": false,
  "message": "Agency signature required",
  "data": null
}

Invalid Signature

{
  "success": false,
  "message": "Invalid agency signature",
  "data": null
}

Expired Signature

{
  "success": false,
  "message": "Agency signature expired",
  "data": null
}