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
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
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
| Public route | Responsibility |
|---|---|
/docs | Overview, environment notice, and reading order. |
/docs/quickstart | UAT prerequisites, scoped-key setup, first request, and response interpretation. |
/docs/guides/... | Business workflows and prerequisites, including the webhooks receiver guide. |
/docs/reference | Read-only reference derived from Partner OpenAPI. |
/docs/testing | UAT access, dedicated fixtures, expected outcomes, and cleanup limits. |
/docs/errors | Existing 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) andx-grant-scope(landlord grant) as separate requirements. An emptyx-grant-scope, as on connect-request creation, reads as “no landlord grant required”, not as missing data.- The global
x-error-codesstatus table. - The top-level
webhooks: partnerEvententry 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
- Understand UAT
Calls read and mutate actual UAT data. There is no Partner API test/live flag.
- 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.
- Store the secret server-side
Use an environment variable. Never place the key in frontend code, source control, URLs, or persistent browser storage.
- Prove authentication
Call
GET /api/partner/v1/mewithx-api-keyat the documented UAT base URL. - 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.
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_urimust match a registered URL exactly. - The partner delivers the approval link.
POST /connect-requestsreturnsapprove_urlandexpires_atto 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:readgrant; 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-Idequal to the bodyid. - Acknowledgement and delivery: persist before returning
2xx; at-least-once, unordered—deduplicate byidand fetch current state through authorised reads. - Outcomes:
408/429/5xxretry within the 24-hour bound;3xxand other4xxare terminal; nothing is backfilled while an endpoint is disabled.
UAT testing and cleanup
- 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.
- 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.
- 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.
| Condition | Required guidance |
|---|---|
| Invalid, expired, or revoked key | Explain credential failure separately from landlord authority. |
| Insufficient permissions or absent/revoked consent | Distinguish the key ceiling from grants; do not recommend indiscriminate permission broadening or consent re-requesting. |
| Concealed resource | A 404 can mean lack of access, not only deletion. |
| Validation or business prerequisite | Explain the relevant field/state prerequisite and correction. |
| Rate limit or service unavailability | Use the documented retry guidance for the operation and preserve the request ID. |
| Idempotency conflict or uncertain write | Explain 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.
- Signed-out users can read all documentation surfaces, including the webhooks guide; management routes remain protected.
- Generate the reference from checked-in OpenAPI, showing separate key/grant requirements (including “no grant required”),
x-error-codes,partnerEventas 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. - Once the self-service portal is delivered, follow account setup and the quickstart to
/mewithout an undocumented prerequisite or embedded credential. - 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. - Reach listing submission/review through the documented property workflow; demonstrate claim prerequisites and separate submission from publication.
- 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.
- 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. - 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.
- Confirm actual UAT notice/base URL, identifier acquisition, human steps, and cleanup limits. Invent no production host or sandbox/test-key behavior.
- 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.
- 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.yamldescribes 59 explicitly mounted operations under/api/partner/v1, authenticated throughx-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. Itsserversentry is/.- The contract carries per-operation
x-key-scope/x-grant-scope, a top-levelx-error-codestable, and a top-levelwebhooks: partnerEventcallback. 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’sPartnerWebhookSection, and the receiver/onboarding guidedocs/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.tsstripsmetadata.modewhen issuing partner keys.docs/superpowers/specs/2026-10-03-partner-api-p1-design.mddefers 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.mddefines the dedicated portal and owner operations. At authoring timefrontend/solidstart/apps/partnerdoes 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/andsrc/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
- Written spec approved
Approved on 2026-10-10 after review revisions.
- Review OpenSpec artifacts
The
partner-developer-integration-experienceproposal, design, specs and tasks were generated ahead of this gate and updated to match; review them and select an execution method. - 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.