Operational Security Controls

This section consolidates operational requirements and recommended practices that improve replay resistance, traceability, network safety, and troubleshooting.

Replay Prevention and Time Discipline

This subsection defines minimum controls to reduce replay risk and avoid failures due to clock skew.

  • Tokens include utc as epoch milliseconds and use UTC±00:00.
  • Because cdata is issued in a short window, token issuers SHOULD ensure time synchronization (e.g., NTP) and minimize delays between token creation and link invocation.
  • If a request is retried, issuers SHOULD generate a fresh token rather than reusing near-expiry tokens.

Request Identifier (x-request-id)

This subsection defines the request identifier used for traceability and operational correlation.

Many APIs define x-request-id as a randomly generated UUID used for traceability. Partners SHOULD log and propagate this identifier end-to-end for troubleshooting and audit correlation.

Type

 Description
x-request-id
String(64)

 (Recommended)
UUID is preferred (36 chars); 64 allows future formats.

Reference ID (refId / pdata) and Indirection Safety

This subsection defines safety guidance for indirection identifiers used in Data Fetch Link flows.

For Data Fetch Link flows, the link includes only a reference identifier (pdata), which maps to refId. Partners SHOULD generate refId with high entropy, avoid embedding PII or predictable business identifiers, and consider using encryption or hashing with server-side mapping if plaintext exposure is a concern.

Type

 Description
pdata (refId)
String(256)

 (Recommended)
Recommended High-entropy, non-sequential identifier; do not embed PII.

Network Security and Environments

This subsection defines allowlisting guidance, domain/callback considerations, and environment separation practices.

  • Allowlisting: When partners enforce inbound allowlists, they may need to register Samsung server IP addresses; operational inbound/outbound IP information should be referenced from Partner Portal card details.
  • Domain/callback context: Callback-based context (e.g., parameters such as cc2) may be required for subsequent calls depending on the integration flow.
  • Environment separation: Partners SHOULD use separate Card IDs/services per environment (test vs production) to avoid cross-environment contamination.

Troubleshooting Quick Checks (Operational)

This subsection provides a minimal checklist for common failures.

  • 401 Unauthorized: Verify Authorization Token signature and time validity; ensure correct API.method and API.path binding.
  • cdata failures: Generate cdata inside click handlers; avoid pre-generation to reduce expiry issues.
  • Network timeouts / 5xx: Confirm allowlist configuration and Partner Portal operational IP references; confirm domain/callback parameters (e.g., cc2) are correctly applied.