Partner portfolios and consent

Klineo's partner platform lets an authorized partner view a reduced portfolio of consenting issuers, prepare issuer-scoped proposals, and apply verified branding to eligible public disclosures. Every issuer remains an independent organization with its own authority and custody boundaries.

A partner declaration alone does not grant access to issuer evidence. Access requires matching issuer consent for the named actor and the exact current partner configuration generation.

Establish bilateral access#

Partner configuration declares the issuer organization IDs in its portfolio and the actors allowed to read portfolios or prepare proposals. An issuer authority then grants consent to a subset of those declared actors.

Consent records bind:

• Partner and issuer organization identities.
• The exact partner resourceVersion and artifactHash.
• Explicit portfolioReaderActorIds and proposalPreparerActorIds.
• Grant time, optional future expiry, and current consent state.

At least one read or proposal-preparation actor must be granted. An issuer cannot grant an actor missing from the partner-side declaration. Consent is versioned evidence, rather than a reusable invitation that silently applies to every future partner configuration.

API workflow#

Partner endpoints use /api/liquidity-studio/v2 and authenticated organization context:

Partner administration requires an organization owner or Klineo operator role. Consent changes require an organization owner, treasury admin, or Klineo operator role. These authority changes also require recent authentication. Read and preparation access depends on the explicit named actors in both declarations; having a broad workspace role does not bypass that check.

Use an idempotency key for mutations and the exact version precondition required by the endpoint. The receipt recovery GET also requires the original preparation's Idempotency-Key header. Existing consent replacement and revocation use the current consent version. Proposal preparation specifically uses the consent resourceVersion in If-Match, not a partner version or proposal hash. Refetch and review after a version conflict.

Read the reduced portfolio#

The response schema is partner-portfolio-view-v2. It identifies the active partner configuration, a generation timestamp, limited brand fields, and one row for each declared issuer.

An issuer row is AVAILABLE only when the current consent is active, unexpired, bound to the current partner generation, and includes the requesting reader. Otherwise the response supplies UNAVAILABLE_NO_BILATERAL_CONSENT without exposing the private issuer payload.

Available rows include consent hash, version, expiry, preparation scope, a reduced issuer-reviewed market-quality score or its unavailability state, active venue count, and reduced draft/validated/active proposal summaries. A proposal summary provides identity, title, status, expiry, and artifact hash; it does not carry the full proposal workspace or execution authority.

Check capturedAt and coverage before interpreting a market-quality value. An available portfolio response does not promise that the market observation is current. The application treats a portfolio view older than sixty seconds as stale and requires refresh. External integrations should also re-resolve before a decision rather than retaining an authorization snapshot indefinitely.

The projection explicitly returns custodyAuthorityGranted: false and crossIssuerMutationAuthorityGranted: false. Missing evidence stays unavailable; do not attempt to fill it by issuing raw cross-organization record queries.

Prepare a proposal#

Proposal preparation requires the partner actor's preparation role and matching active issuer preparation consent. The target issuer must be declared in the partner portfolio. The current route accepts a proposal expiring within twenty-four hours and strips internal approvals from the prepared material.

The service verifies that the issuer consent author remains an active organization member with issuer authority, then persists an auditable preparation event in the issuer's inbox bound to the current partner and consent hashes. requestExternalDelivery defaults to false. With that default, preparation requires no external integration provider, returns deliveryJobId: null, and reports deliveryState: 'NOT_REQUESTED' through the status endpoint.

The issuer explicitly imports or declines the packet using /partner-preparations/{eventId}/import or /decline, with an idempotency key, an audit reason, and the current consent resourceVersion in If-Match. Import rechecks the bilateral consent and member generations, validates the proposal and its admission evidence, and creates an issuer proposal for ordinary review. A successful import returns issuerReviewRequired: true and executionAuthorityGranted: false. Decline records the decision without creating a proposal. A packet that has already been imported or declined cannot receive a second decision.

External delivery is optional. Set requestExternalDelivery: true only when you intend to enqueue it through a configured partner integration. The service requires exactly one current healthy partner integration provider with valid signing material, binds its generation to the packet, and returns a delivery job ID. Delivery remains fenced against current consent so an old queued packet cannot serve as continuing permission after consent changes. Read the status endpoint for delivery progress and the separate issuer decision.

A 202 response confirms that preparation was accepted; it does not prove external delivery, issuer import, proposal approval, or execution. With the default request, it describes a saved issuer inbox packet. With explicit external delivery, it additionally describes queued delivery work.

If the preparation response is lost or the page reloads before it is received, retain the original operation key and call GET /partner-preparation-receipts/{partnerId}?issuerOrganizationId=... with that exact key in the Idempotency-Key header. Recovery uses the authenticated initiating actor and partner organization, the same partner and issuer target, and current membership, active partner declaration, named preparer and active bilateral proposal-preparation grant. It requires no proposal body, audit reason or If-Match header and performs no preparation admission.

The HTTP 200 response is either data: { state: 'ACCEPTED', receipt: ... } or data: { state: 'UNRESOLVED' }. ACCEPTED verifies the original durable v2 completion with HTTP 202 and its matching immutable preparation event. The receipt contains the preparation event/hash, proposal ID, partner/actor/organization and issuer IDs, original consent and partner configuration versions/hashes, nullable delivery job ID, and the explicit authority flags. It excludes the proposal packet and audit reason. Its original committed consent metadata may differ from the currently authorized consent; keep that historical binding when recovering the receipt. Success and denial responses use Cache-Control: private, no-store.

UNRESOLVED covers missing, in-flight, failed, unsupported or unverifiable completion evidence. It does not prove the preparation was rejected. Keep the pending operation available for another recovery read; do not automatically retry the POST, replace its key or submit a new preparation. Once the receipt is recovered, use its preparationEventId with the status endpoint. A deliberate new preparation requires a new review and a new operation key.

Preparation records explicitly state that execution, Safe, custody, and policy-expansion authority are not granted. The issuer must review the resulting material and follow the ordinary proposal, approval, policy, and execution flow. A partner-prepared packet cannot substitute for issuer authorization or a signed transaction.

Revoke, expire, or update consent#

Revoking consent appends a revoked generation; expiry also makes consent ineligible. A change to the partner configuration invalidates consent bound to the earlier configuration until the issuer grants a matching new generation. The backend evaluates these conditions when resolving a portfolio or admitting preparation.

Revocation prevents further eligible access through the service. It cannot remove information that a recipient already downloaded, copied, or published. Consumers should honor current access and disclosure choices, avoid retaining unnecessary issuer evidence, and refresh consent before initiating another action.

Verified branding#

Each claimed partner domain requires signed domain verification evidence from a registered provider. The service checks evidence validity and rejects a domain already bound to a different partner. Host-based branding depends on the trusted request-host resolution and the current active configuration; arbitrary forwarded headers are not proof of domain ownership.

To find an existing onboarding challenge, an authorized administrator reads GET /partner-domain-challenges?partnerId=.... The optional partner filter limits the current organization's directory; each response remains data: Challenge[] with at most 1000 entries, newest first. For older entries, retain the same filter and pass the last returned ID as beforeChallengeId. A page shorter than 1000 entries ends traversal. Unknown cursors and cursors belonging to another organization or selected partner return an empty array. A directory entry alone does not verify ownership or admit a partner configuration; read the exact challenge and use its current signed proof for that workflow.

The registered logo is a bounded, content-addressed PNG asset. Public rendering uses a same-origin path tied to its content hash rather than an arbitrary remote image URL. Brand accent tokens must meet the text-contrast checks used by the application.

For a branded Liquidity Passport, the signed reportBrand.sourceBinding identifies the exact partner configuration and bilateral consent generations. Name, accent color, and any logo hash must match the current registered values. The public service rechecks that binding when serving the Passport. Revoking consent, superseding the partner generation, or invalidating its logo can therefore make an older branded Passport unavailable.

Branding changes how eligible evidence is presented. It does not make the partner the owner of issuer funds, enlarge an execution policy, or turn reported market quality into an investment guarantee.