中文版

Partner Portal — Developer Integration Experience

Add public, guided integration documentation to the partner portal so developers can make their first authenticated UAT request and implement landlord and listing workflows correctly. Generate the read-only API reference from the shipped Partner OpenAPI contract, with explicit consent, permission, visibility, retry, and test-data guidance.

  • Predecessor 2026-10-09-partner-self-serve-onboarding-design
  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6-luna · diagrams mermaid

Give partner developers a public, guided path from their first authenticated UAT request to correct landlord and listing workflows. Keep the API reference tied to the shipped OpenAPI contract, explain human claim and consent steps, and never turn documentation into a credential-bearing request runner.

Decisions and tradeoffs

  • AudiencePartner integration developers
  • SurfacePublic docs inside the partner portal
  • EnvironmentExisting UAT, not a sandbox
  • LanguagesEnglish / Malay / Chinese

Guided documentation plus contract-derived reference

Quickstart, business guides, UAT testing, errors/recovery, and a read-only endpoint reference in the dedicated portal.

Developers need to understand permissions, consent, account claim, resource visibility, and business sequencing—not just obtain credentials or inspect endpoint schemas. The goal is a successful request and an authorised property/listing submission with no undocumented prerequisite or staff explanation.

Rejected: reference-only documentation leaves workflow reconstruction to the developer. An interactive explorer adds secret-handling and accidental-write risks without being required.

Access
Documentation is public; account, profile, and key management remain authenticated.
Examples
Copyable cURL with environment-variable placeholders, expected outcomes, and instructions for obtaining every identifier.
Contract
The checked-in Partner OpenAPI document supplies methods, paths, schemas, responses, and operation details.
Secrets
No real developer credential is embedded, retrieved, or persisted by documentation.

Architecture and content ownership

Guides explain integration sequencing; the checked-in contract determines endpoint details. The documentation has no request runner or owner-secret lookup
Guides explain integration sequencing; the checked-in contract determines endpoint details. The documentation has no request runner or owner-secret lookup.
Public routeResponsibility
/docsOverview, environment notice, and reading order.
/docs/quickstartUAT prerequisites, scoped-key setup, first request, and response interpretation.
/docs/guides/...Business workflows and prerequisites, including the webhooks receiver guide.
/docs/referenceRead-only reference derived from Partner OpenAPI.
/docs/testingUAT access, dedicated fixtures, expected outcomes, and cleanup limits.
/docs/errorsExisting errors and actionable recovery.

Explanatory guides

Version-controlled prose owns workflow sequencing, prerequisites, security explanations, and example narratives. Guides link to their reference operations; API changes affecting a workflow require guide updates.

Authoritative API reference

backend/go/openapi/partner-v1.yaml owns endpoint details. Generate the reference during the portal build—not only schemas.

The reference must render:

  • x-key-scope (key ceiling) and x-grant-scope (landlord grant) as separate requirements. An empty x-grant-scope, as on connect-request creation, reads as “no landlord grant required”, not as missing data.
  • The global x-error-codes status table.
  • The top-level webhooks: partnerEvent entry as an outbound callback the partner receives, never as a callable operation.
  • The contract’s conditional-mount statement on handover operations, so they are not shown as available in every deployment.

Validate OpenAPI and internal guide/reference links during the build. Do not maintain a competing handwritten endpoint catalogue or fetch a remote contract whose revision can diverge from the app. Existing backend contract-drift coverage remains authoritative for agreement with mounted operations.

Deployment information

Show the configured UAT API base URL prominently and consistently. Resolve it from approved portal deployment configuration: no guessed host, unrelated landlord fallback, internal service URL, invented production URL, or selectable production environment. The contract’s servers entry is /, so it supplies no host. Missing or invalid configuration fails the documentation build; pages never publish a fabricated or placeholder host.

Examples use variables for the base URL, key, and resource IDs. Explain where each value comes from; never substitute an owner’s actual secret.

Authentication-first quickstart

  1. Understand UAT

    Calls read and mutate actual UAT data. There is no Partner API test/live flag.

  2. Set up identity and credentials

    Register or sign in, verify the account, create the partner, and issue a named key with explicitly selected permissions. Link to delivered management screens instead of duplicating controls. The quickstart is published only once the self-service portal ships; until then, partner creation, key issuance and redirect registration are platform-admin steps and any interim content says so.

  3. Store the secret server-side

    Use an environment variable. Never place the key in frontend code, source control, URLs, or persistent browser storage.

  4. Prove authentication

    Call GET /api/partner/v1/me with x-api-key at the documented UAT base URL.

  5. Interpret and continue

    Explain the returned partner identity and permission ceiling, then branch into new-landlord or existing-landlord workflows.

Provide copyable cURL, implemented response shapes, expected outcomes, and instructions for acquiring each variable. The page is a guide—not a browser client.

Business workflow guides

Every guide includes prerequisites, required key permissions and landlord-grant scopes, identifier acquisition, ordered requests, expected responses/states, human participation, failure recovery, supported retries, and applicable cleanup. Examples come from implemented contracts, not design-only endpoints.

Account claim and landlord consent are distinct. The workflow explains real human and review steps; it does not bypass them or imply provisioning grants consent-only scopes
Account claim and landlord consent are distinct. The workflow explains real human and review steps; it does not bypass them or imply provisioning grants consent-only scopes.

Onboard a new landlord

  • Explain provisioning outcomes, stable partner references, and repeated-attempt handling.
  • Claim secrets travel only through platform email, never to the partner. Explain claim status and the claim prerequisite for listing submission.
  • Provisioning neither silently connects an existing account nor grants consent-only scopes.

Connect an existing landlord

  • Register redirect URLs through the portal once delivered (platform admins until then); redirect_uri must match a registered URL exactly.
  • The partner delivers the approval link. POST /connect-requests returns approve_url and expires_at to the partner; the platform does not send it. The URL is single-use, expires after 24 hours, and polling never returns it again—a lost response means creating a new request.
  • Explain approval, denial, expiry, and determining access. Distinguish consent credentials from account-claim credentials (which travel only by platform email) and key ceilings from grants.
  • Re-approval replaces the complete grant scope set: omitted scopes are removed, not accumulated. A key or known landlord ID grants no unrestricted access.

Prepare and submit a listing

  • Create/find an authorised property, supply media and ownership proof, prepare the listing, and submit for review.
  • Explain prerequisites, resulting review state, partner-origin visibility, and attribution rules.
  • Submission is not publication. Do not suggest changing identifiers or credentials to access concealed resources.

Supported downstream operations

Cover delivered tenancy, agreement, payment, handover, contact, enquiry, and offer operations. Follow supported methods, transitions, ceilings, consent-only scopes, and property-origin boundaries. Handover availability depends on the deployment wiring the handover handler.

Offers are read-only: no creation, countering, acceptance, decline, or withdrawal. Archived history follows each resource’s contract; never promise visibility of an entire landlord account.

Receiving webhooks

Partner webhooks are already delivered, so a webhooks guide covers the receiving side, derived from the contract’s webhooks: partnerEvent entry:

  • Eligibility: an enabled endpoint bound to an active, unexpired, read-capable key; an active enquiries:read grant; partner-created properties; five event types.
  • Envelope: minimal identifiers—a signal, not a state snapshot.
  • Signature: Webhook-Signature: v1=<hex HMAC-SHA256> over <Webhook-Timestamp>.<exact body> with the base64-decoded secret; five-minute window, constant-time comparison, Webhook-Id equal to the body id.
  • Acknowledgement and delivery: persist before returning 2xx; at-least-once, unordered—deduplicate by id and fetch current state through authorised reads.
  • Outcomes: 408/429/5xx retry within the 24-hour bound; 3xx and other 4xx are terminal; nothing is backfilled while an endpoint is disabled.

UAT testing and cleanup

  1. Use dedicated test identities

    Explain how to obtain landlord accounts and create partner-owned resources. Do not rely on arbitrary existing UAT accounts, properties, grants, or IDs.

  2. Expose genuine prerequisites

    Separate API-created fixtures from human claim, consent, and administrative review. State any required staff setup before the affected workflow, not behind an apparent self-service step.

  3. Clean up through supported operations

    Use supported archive/delete/revoke operations and explain their limits. Do not promise a complete reset or destroy someone else’s records. Revoking a credential or grant does not delete business data.

Errors, retries, and secret handling

Explain the existing envelope {error:{code,message,fields?},request_id} and retaining the request ID for diagnosis. Do not introduce a new error contract.

ConditionRequired guidance
Invalid, expired, or revoked keyExplain credential failure separately from landlord authority.
Insufficient permissions or absent/revoked consentDistinguish the key ceiling from grants; do not recommend indiscriminate permission broadening or consent re-requesting.
Concealed resourceA 404 can mean lack of access, not only deletion.
Validation or business prerequisiteExplain the relevant field/state prerequisite and correction.
Rate limit or service unavailabilityUse the documented retry guidance for the operation and preserve the request ID.
Idempotency conflict or uncertain writeExplain matching replay, changed-body conflict, and the operation’s reconciliation rules; never blindly replay writes without the applicable contract.

Describe supported Idempotency-Key behavior per endpoint and provisioning’s separate partner-reference semantics. A lost write response is not blanket permission to retry. Do not promise idempotent key-secret re-delivery.

Localisation and accessibility

Use the portal’s English/Malay/Chinese convention for narrative content, navigation, notices, and copy feedback. Keep requests, field names, paths, permission identifiers, headers, and wire error codes unchanged.

Review translations of claim, consent, permissions, visibility, UAT safety, and retries for equivalent meaning. Provide accessible headings, navigation, code blocks, copy controls, and status feedback. Mobile reading must preserve request content and reference access. No separate visual framework or unrelated portal/rental redesign.

Verification and acceptance

Implementation combines build checks, existing contract coverage, real UAT requests, and rendered documentation. Authoring this design requires no product code, runtime test, or portal build.

  1. Signed-out users can read all documentation surfaces, including the webhooks guide; management routes remain protected.
  2. Generate the reference from checked-in OpenAPI, showing separate key/grant requirements (including “no grant required”), x-error-codes, partnerEvent as non-callable, and conditional handover mounting. Invalid input, broken internal guide/operation links, or missing/invalid base-URL configuration fails build verification rather than publishing a partial reference.
  3. Once the self-service portal is delivered, follow account setup and the quickstart to /me without an undocumented prerequisite or embedded credential.
  4. Execute new-landlord and existing-landlord consent paths with dedicated UAT accounts; observe identity, claim/grant state, and authority—not only successful statuses. Only the creation response carries approve_url; polling never does; the partner delivers it.
  5. Reach listing submission/review through the documented property workflow; demonstrate claim prerequisites and separate submission from publication.
  6. Exercise representative downstream reads/writes and denial cases with authorised fixtures; prove ceilings, grants, origin boundaries, and unsupported-operation limits. Do not advertise unavailable operations, including unwired handover routes, as runnable.
  7. Verify the webhook signature example with locally signed fixtures: accept a valid signature; reject a tampered body, stale timestamp, or mismatched Webhook-Id. No real secret in evidence; a live UAT delivery is optional.
  8. Exercise representative idempotent replay/conflict and error recovery without printing credentials. Preserve backend operation/contract regressions rather than add source-text or duplicated-catalogue tests.
  9. Confirm actual UAT notice/base URL, identifier acquisition, human steps, and cleanup limits. Invent no production host or sandbox/test-key behavior.
  10. Use the repo-approved ego-lite browser workflow to inspect rendered navigation, reference links, copy controls, accessibility, mobile reading, and all three locales. Guide content and chrome follow the locale; reference contract descriptions stay English. Copied examples contain placeholders only.
  11. Before UAT writes, follow repository safety rules: development environment and documented UAT database host/name. Automated database integration suites use disposable databases. Revoke walkthrough keys and perform only supported owned-fixture cleanup.

Foundations, dependencies, and scope

Observed foundations and concrete source references
  • backend/go/openapi/partner-v1.yaml describes 59 explicitly mounted operations under /api/partner/v1, authenticated through x-api-key. It excludes frontend/session claim and consent endpoints and documents ceilings, grants, live-mode visibility, origin restrictions, claim prerequisites, errors, rate limits, and endpoint-specific idempotency. Its servers entry is /.
  • The contract carries per-operation x-key-scope/x-grant-scope, a top-level x-error-codes table, and a top-level webhooks: partnerEvent callback. Handover operations are mounted only when the handover handler is wired.
  • Partner webhook delivery is implemented: Go worker, admin handlers and persistence under backend/go/internal/modules/rental/, the panel’s PartnerWebhookSection, and the receiver/onboarding guide docs/backend/go/guides/partner-api-webhooks.md. Configuration is admin-only.
  • Consent redirect URIs are currently editable only through admin partner endpoints (admin_partner_handler.go) and panel partner screens; owner editing arrives with the self-service portal.
  • backend/bun/apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts strips metadata.mode when issuing partner keys.
  • docs/superpowers/specs/2026-10-03-partner-api-p1-design.md defers sandbox/test mode and directs integration testing to UAT. Partner requests do not expose landlord API test-mode rows.
  • docs/superpowers/specs/2026-10-09-partner-self-serve-onboarding-design.md defines the dedicated portal and owner operations. At authoring time frontend/solidstart/apps/partner does not exist; this design extends that prerequisite, not evidence that it shipped.
  • The existing landlord developer guide is in frontend/astro/apps/rental/src/pages/developers/ and src/docs/landlord-api-v1.md. Its deployment-aware host injection is a reference for avoiding handwritten URLs—not permission to copy landlord paths or prefixes.

Implement against the delivered self-service portal and shipped backend contracts. frontend/solidstart/openspec/changes/partner-self-serve-portal/design.md remains responsible for authentication, ownership, profile, and key lifecycle. This slice adds documentation and navigation only.

Explicit non-goals

No dedicated sandbox, production deployment, environment switch, partner test/live keys, interactive explorer, SDK generation, new business endpoints, consent bypass, webhook self-service (setup, test-send, replay), translation of contract prose, automatic test-data provisioning/reset, diagnostic dashboards, or unrelated refactoring/rental-user work.

Approval and implementation gates

  1. Written spec approved

    Approved on 2026-10-10 after review revisions.

  2. Review OpenSpec artifacts

    The partner-developer-integration-experience proposal, design, specs and tasks were generated ahead of this gate and updated to match; review them and select an execution method.

  3. Implement and prove

    Deliver against the real portal/API prerequisites and collect both UAT and browser evidence.

Committing the design document or OpenSpec artifacts does not authorise implementation. The source specifies verification and dependency gates; it does not add deployment infrastructure or a data migration.