P2PSDK Control Plane API integration guide

The P2PSDK Control Plane API exposes authentication, profile, applications, managed users, analytics, billing, webhooks, news, and proxy-targeting resources through a public HTTP contract.

This guide explains how to structure an integration. Exact parameters, request bodies, responses, and generated examples live in the interactive API explorer and its downloadable OpenAPI document.

Start from the public contract

The downloadable OpenAPI document is the canonical machine-readable description used by the documentation. The public build removes internal operations, prunes unused components, and points examples at the sandbox environment.

Every public operation has a stable operationId, summary, tag, and response contract. Generate client helpers from the published document if that suits the host application, but preserve the HTTP status and error semantics rather than collapsing all failures into a single client exception.

Use stable operationId values and OpenAPI paths in engineering tickets and runbooks. The interactive explorer provides convenient hash navigation, while the downloadable document remains the durable machine-readable contract.

Choose the authentication lifecycle

The API includes login, signup, token refresh, social authentication, password reset, profile, and account API-key operations. The correct mechanism depends on whether the caller is acting as an interactive account session or as an approved service integration.

Keep credentials out of URLs, logs, browser storage decisions that have not been security-reviewed, and copied support payloads. A refresh flow should update the active credential atomically and should not replay a failed mutating request unless the application can prove the operation is safe to retry.

Start with the Authentication section in the API explorer and verify the security requirements shown for the specific operation.

Carry a request identifier end to end

Every endpoint accepts an optional X-Request-ID request header and returns the final request identifier in the response. Generate a unique value at the boundary of the calling system and retain the returned value with sanitized operational logs.

That identifier gives support and backend operators a shared correlation key without placing credentials or request bodies in tickets. If an upstream gateway replaces an invalid or duplicate identifier, the response value is the one that should be recorded.

Model ownership before writing calls

The API groups operations by business resource rather than by UI screen. Establish which account or service owns each object before composing workflows:

• account API keys belong to the authenticated account;
• applications represent seller application review and runtime configuration;
• managed users belong to a buyer account;
• data transactions form a balance audit trail;
• invoices and pricing describe buyer data purchases;
• payouts describe seller payment flows;
• webhook subscriptions deliver asynchronous account events.

Do not infer cross-resource ownership from similar identifiers. Follow the path parameters and authenticated context in the operation contract.

Make retries operation-specific

Read operations can usually be retried after transient network failures with bounded backoff. Mutating operations require more care. A timeout does not prove that the server rejected a create, update, payout, or test-webhook request.

Before retrying, use the available read operation or resource list to determine whether the intended state already exists. Record the request identifier and surface ambiguous outcomes for reconciliation rather than silently duplicating work.

Test against the sandbox contract

The interactive explorer keeps “Try it” disabled unless the public staging host and its CORS policy are explicitly enabled. Server-side integrations can test directly against the approved sandbox supplied during onboarding.

For each workflow, retain evidence for authentication failure, validation failure, missing resources, authorization boundaries, rate or transient failures, and the successful response. Begin with the API explorer and identify each implementation step by its exact operationId and OpenAPI path.