中文版

Partner API — Self-Service Signup and Key Management

Verified human accounts can create an active external partner and manage API keys without administrator involvement. A dedicated portal gives each account sole ownership of one partner while preserving separate service identities, landlord consent, and once-only secret disclosure.

  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6.1-sol · diagrams mermaid

A verified human account can create an active external partner and manage its API keys without an administrator. One creator owns one partner; a dedicated portal preserves separate service identities, landlord consent, and once-only credential disclosure.

Decisions and review status

  • EligibilityOpen signup · verified human
  • OwnershipOne account · one partner
  • SurfaceDedicated SolidStart portal
  • CredentialsNamed, explicitly scoped keys

Direct creator ownership

Nullable, unique owner_user_id on the partner record; one creator per self-service partner and at most one partner per account.

The single-owner model needs no membership lookup or role system. Authority is local to that partner, not a platform-wide admin role.

Rejected: a separate ownership table adds a table and lookup with no present need for multiple owners; organisations and invitations add unnecessary membership semantics.

DecisionChosen contract
SignupNo invitation or administrative approval; email verification before creation or issuance.
New partnerActive, external; defaults are server-assigned, never client-selectable.
Human versus API identityCreator login manages the partner; a separate non-interactive service user owns its keys.
Key lifecycleMultiple named keys, explicit permissions, optional expiry, safe listing, and revocation.
Changing credentialsIssued permissions and expiry are fixed: issue a replacement and revoke the old key.
Existing partners and callbacksAdmin-created partners remain admin-managed; no claims/backfill. Webhooks remain admin-managed.

Intent and access boundary

Partner developers must be able to register, create their partner identity, and obtain usable credentials without manual admin setup. Ongoing self-service includes permitted profile edits, additional keys, safe metadata inspection, and revocation.

Allowed access is narrowed by key permissions, landlord consent, and resource visibility; signup does not bypass any layer. Key ceiling Landlord consent Visible resources Allowed access
Successive access constraints, not new grants: an issued key still passes the existing landlord-consent and resource-visibility checks.

Architecture and identities

Human sessions authorise management; the separate service identity remains behind Partner API keys. Both backends enforce their own persisted-ownership checks
Human sessions authorise management; the separate service identity remains behind Partner API keys. Both backends enforce their own persisted-ownership checks.

Dedicated portal

frontend/solidstart/apps/partner reuses shared authentication, UI, and server-proxy conventions. Registration, sign-in, verification, recovery, onboarding, profile, and keys share the existing identity store. Proxies carry human context, not an API key impersonating an owner.

Go partner authority

Owns partner records, creator ownership, profile mutations, and onboarding orchestration. Owner assignment and partner insertion commit together; database uniqueness enforces one partner per account and preserves slug/service-user uniqueness.

Bun credential authority

Owns human auth, genuine service-user provisioning, issuance, listing, and revocation. Each key operation resolves the human session and current persisted ownership. Both backend representations share the owner column; Bun keeps no second registry.

Ownership and authorisation rules

  • owner_user_id is nullable for admin-created partners and unique when present. Keep the existing auth ID representation; account IDs are not assumed to be UUIDs.
  • The server assigns ownership. Reject client-supplied owner, service identity, tier, status, and other privileged mutation fields.
  • Known partner/key IDs confer no authority. Check persisted ownership on every operation; foreign partner/key access returns not found without metadata.
  • Revocation checks both partner key configuration and service-user reference. A service-user account is never a human creator.
  • No ownership transfer or attachment of an existing admin-created partner. Creator authority comes from ownership, not a global auth role.
  • Apply existing cookie-session CSRF/origin protections and configure only the new portal's allowed origin; do not trust arbitrary origins.

Signup and onboarding

  1. Register or sign in

    Use a new or existing human account in the shared account system.

  2. Verify email

    Show guidance when unverified. Backends block partner creation and key issuance until verification succeeds.

  3. Resolve existing ownership

    Existing owners open their overview; no second partner creation flow.

  4. Create partner

    Request a display name and unique slug using existing validation. Explain that the slug is permanent. The server creates an active external partner and assigns the human creator plus separate service identity.

  5. Issue the first key separately

    Require a key name and explicit non-empty valid permissions; expiry is optional. Creation never automatically mints full access.

  6. Reveal once, then manage metadata

    Offer copying and a cannot-retrieve-again warning. Leaving disclosure returns to safe metadata. A failed or abandoned first-key step does not invalidate the created partner.

Concurrency and recovery

Recovery proves ownership rather than matching a slug or service identity. An uncertain result is never permission to claim another partner
Recovery proves ownership rather than matching a slug or service identity. An uncertain result is never permission to claim another partner.
  • Check existing ownership and slug availability first; enforce uniqueness again on insert.
  • Reserved-email recovery accepts only genuine non-interactive service users. Interactive collisions remain conflicts, not account conversions.
  • Return an existing partner only when its persisted owner is the authenticated creator. Name, slug, service-user ID, and reserved email are not ownership evidence.
  • After a conflict or uncertain insert, resolve committed state: same-owner record may be returned; foreign or admin-managed identity cannot be claimed.
  • Concurrent different-slug submissions by one account produce at most one partner. The winning record cannot be changed or have keys issued against an uncommitted candidate.
  • A lost race or insert failure can leave an unused genuine service user without onboarding-created keys or landlord grants. No destructive cleanup worker is added; later slug creation can reuse it only under the same safe rules.

Profile and suspension

Owner-editable
Display name and valid registered consent redirect URLs; preserve existing consent matching/security rules.
Immutable to owner
Slug, tier, status, service identity, and ownership.
Suspended partner
Profile/key metadata reads and key revocation remain available. Profile edits, new issuance, and resource requests with existing keys are blocked.
Administrator
Retains management, suspension, and exclusive reactivation authority.

Keys and secret lifetime

  • Require a name and explicitly selected valid permissions. Missing selection never means full access; unknown actions and silent authority expansion are rejected.
  • Permissions are a ceiling, not consent. Consent-only records still require existing landlord authorisation.
  • Optional expiry follows the existing auth contract. Reject invalid or non-positive durations rather than silently mint an unexpired key.
  • Force configId: 'partner', the persisted service user, and existing prefix grp_ server-side. Client metadata cannot select identity or bypass ownership.
  • Issued permissions and expiry cannot be edited: create a replacement, then revoke the old key.
  • Use a non-cacheable issue response and a transient disclosure view. Clear the secret when the view closes or the owner signs out.
  • Keep secrets out of URLs, logs, persistent browser storage, analytics, and cached metadata queries. Lost-response metadata must remain manageable.
  • Revocation verifies human ownership and service/config binding. Expired or revoked keys cannot authorise Partner API calls.

Errors and honest state

Reuse existing backend envelopes and frontend handling. Retain non-secret form input for correction, not secrets for recovery. Repeat onboarding may recover a committed owned partner; issuance does not promise idempotent disclosure.

ConditionRequired outcome
No human sessionAuthentication required; direct to sign-in.
Unverified creation or issuanceVerification required; no mutation.
Already owns a partnerResolve existing ownership for navigation/recovery; no second partner.
Foreign slug or service identityConflict; no claims or management metadata disclosure.
Invalid name, slug, permissions, expiry, redirect, or privileged fieldValidation error; no successful mutation.
Another owner's partner or keyNot found; no metadata or credential change.
Suspended profile edit or issuanceForbidden; safe reads and revocation remain available.
Auth, database, or provisioning unavailableRetryable service error; no fabricated success or ownership fallback.

Existing code and integration

Dependencies are the existing Partner API identity, key validation, landlord consent, shared authentication, and frontend server-proxy conventions. These observed foundations do not mean self-service is implemented.

Concrete integration references
  • backend/go/internal/modules/rental/domain/entity/partner.go: partner identity, active/suspended status, external/first-party tiers, service user, and redirects; currently no human owner.
  • backend/go/internal/modules/rental/application/usecase/admin_partner.go: validates creation, provisions a Bun service user, and recovers some collisions. Administrative recovery is not human ownership evidence.
  • backend/go/internal/modules/rental/adapter/outbound/client/bun_partner_client.go: existing internal provisioning client.
  • backend/bun/apps/monolith/src/api-gateway/routes/internal.routes.ts: creates/recovers partner+{slug}@partners.invalid; recovery requires role partner and no credential accounts, rejecting interactive collisions.
  • backend/bun/apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts: admin-only key creation, permission catalogue, service-user binding, partner configuration/prefix, and sanitised metadata.
  • Existing Bun admin issuance defaults omitted permissions to the full catalogue. Owner issuance must require explicit selection instead.
  • The frontend admin helper projects safe metadata and issues/revokes keys; it is not creator authorisation.

Verification and success criteria

Keep deterministic authorisation, concurrency, recovery, and credential regressions. Tests alone are not proof: exercise the actual portal and Partner API using the repo-approved browser workflow and safe UAT/disposable environments.

  1. New and existing verified accounts create an active external partner and issue a usable selected-permission key without an admin.
  2. Unauthenticated, unverified, and service-user identities cannot create a human-owned partner or issue self-service keys.
  3. Concurrent requests enforce one owner/partner; retries cannot attach foreign or admin-managed records.
  4. A second account cannot inspect, edit, issue, or revoke another account's partner credentials through known IDs or forged fields.
  5. Safe metadata excludes secret/hash fields; raw secrets appear only at issuance, never in storage, logs, or cached lists.
  6. Missing/empty selections and catalogue-external resources/actions are rejected. Issued authority matches exactly; consent and visibility still apply.
  7. Actual API calls reject expired/revoked keys. Suspension blocks resource use, profile edits, and issuance while preserving safe reads/revocation.
  8. Provisioning-success/insert-failure and lost-insert-response recovery are safe. Failed/lost issuance leaves the partner manageable without secret recovery.
  9. Invalid redirects are rejected; consent matching/security is preserved.
  10. Existing admin-created partners, administrative key issuance, and service provisioning work without claims or backfills.

Non-goals and next gate

  • No organisations, memberships, invitations, partner switcher, ownership transfer, partner deletion, or admin approval queue.
  • No second auth system, unrestricted landlord access, secret retrieval, or editing issued-key permissions.
  • No webhook self-service or changes to existing enquiry/offer/webhook resource contracts.

The webhook design, 2026-10-09-partner-api-webhooks-design.md, remains authoritative for admin-managed callback setup. A partner can onboard without a callback; setup stays a separate administrative operation.