Skip to navigation
Security & Operations

Agent SDK Secrets & HMAC Signing

Protect Agent API credentials and understand how the SDK generates timestamped, replay-resistant HMAC-SHA256 request signatures.

View as Markdown

Agent SDK requests are authenticated with a partner API secret. Keep that secret inside a trusted backend service and let the SDK generate signing fields whenever possible.

Two signing protocols

Agent SDK signing uses sorted request fields, a seconds-based timestamp, and a nonce. Direct Developer API requests use the separate process described in Request Signing. Do not reuse one payload format for the other.

Signing rule

For Agent SDK requests:

  1. Exclude the sign field.
  2. Omit fields with empty values.
  3. Sort the remaining field names in ASCII order.
  4. Join the fields as k=v&k2=v2.
  5. Calculate the HMAC-SHA256 hexadecimal signature with apiSecret.

Array values are serialized as compact JSON before joining the signing payload. For example, platformUserIds signs as ["1188041528"], giving platformUserIds=["1188041528"] in the k=v payload. Preserve the array element order, double quotes and string IDs; do not insert formatting spaces or use Java List.toString() (such as [1188041528]). The SDK handles this serialization automatically.

The SDK should build this value from the same data it sends. Changing a signed field after signature generation causes verification to fail.

SDK-managed fields

FieldSourceDescription
agentCodeSDK configPartner agent code.
timestampCurrent server timeUnix timestamp in seconds.
nonceSecure random valueReplay-protection random string.
signHMAC-SHA256Request signature.
currencyDefault currencyUsed when transfer/account APIs omit currency.

Secret storage

  • Load apiSecret from a backend secret manager or protected runtime configuration.
  • Never place the secret in frontend bundles, mobile apps, desktop clients, screenshots, or support tickets.
  • Keep credentials for development, staging, and production separate.
  • Limit access to the services and operators that require it.
  • Redact request signatures, authorization values, and secrets from logs.
  • Revoke and replace credentials when exposure is suspected.

Clock and replay protection

The SDK includes timestamp and nonce to reduce replay risk. Keep backend clocks synchronized and do not reuse a manually constructed nonce. If signature validation fails, confirm the configured secret, server time, serialized fields, and environment before retrying.

Integration checklist

CheckExpected result
Secret locationBackend-only secret storage.
EnvironmentBase URL and credential belong to the same environment.
Field handlingSDK generates timestamp, nonce, and sign.
LoggingBusiness IDs remain visible while credentials are redacted.
RotationCredential owner and replacement process are documented.
Agent SDK Overview

Review the recommended backend integration flow.

Webhooks & Idempotency

Verify callback signatures and prevent duplicate processing.

SDK Troubleshooting

Diagnose signature, clock, environment, and request issues.