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
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
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.
| Decision | Chosen contract |
|---|---|
| Signup | No invitation or administrative approval; email verification before creation or issuance. |
| New partner | Active, external; defaults are server-assigned, never client-selectable. |
| Human versus API identity | Creator login manages the partner; a separate non-interactive service user owns its keys. |
| Key lifecycle | Multiple named keys, explicit permissions, optional expiry, safe listing, and revocation. |
| Changing credentials | Issued permissions and expiry are fixed: issue a replacement and revoke the old key. |
| Existing partners and callbacks | Admin-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.
Architecture and identities
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_idis 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
- Register or sign in
Use a new or existing human account in the shared account system.
- Verify email
Show guidance when unverified. Backends block partner creation and key issuance until verification succeeds.
- Resolve existing ownership
Existing owners open their overview; no second partner creation flow.
- 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.
- Issue the first key separately
Require a key name and explicit non-empty valid permissions; expiry is optional. Creation never automatically mints full access.
- 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
- 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 prefixgrp_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.
| Condition | Required outcome |
|---|---|
| No human session | Authentication required; direct to sign-in. |
| Unverified creation or issuance | Verification required; no mutation. |
| Already owns a partner | Resolve existing ownership for navigation/recovery; no second partner. |
| Foreign slug or service identity | Conflict; no claims or management metadata disclosure. |
| Invalid name, slug, permissions, expiry, redirect, or privileged field | Validation error; no successful mutation. |
| Another owner's partner or key | Not found; no metadata or credential change. |
| Suspended profile edit or issuance | Forbidden; safe reads and revocation remain available. |
| Auth, database, or provisioning unavailable | Retryable 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/recoverspartner+{slug}@partners.invalid; recovery requires rolepartnerand 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.
- New and existing verified accounts create an active external partner and issue a usable selected-permission key without an admin.
- Unauthenticated, unverified, and service-user identities cannot create a human-owned partner or issue self-service keys.
- Concurrent requests enforce one owner/partner; retries cannot attach foreign or admin-managed records.
- A second account cannot inspect, edit, issue, or revoke another account's partner credentials through known IDs or forged fields.
- Safe metadata excludes secret/hash fields; raw secrets appear only at issuance, never in storage, logs, or cached lists.
- Missing/empty selections and catalogue-external resources/actions are rejected. Issued authority matches exactly; consent and visibility still apply.
- Actual API calls reject expired/revoked keys. Suspension blocks resource use, profile edits, and issuance while preserving safe reads/revocation.
- Provisioning-success/insert-failure and lost-insert-response recovery are safe. Failed/lost issuance leaves the partner manageable without secret recovery.
- Invalid redirects are rejected; consent matching/security is preserved.
- 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.