docs(connectors): connection ownership + act-as-artist authority contract

Merged
SW
3mo ago
+71-0

Summary

Contract-first PR of the P1 connector re-key chain for https://github.com/recoupable/chat/issues/1860. Merge order: docs → database → api — this contract merges first, before the api re-key implements it.

Documents the connection-ownership + authority model decided in chat#1860 (2026-07-08):

  • Association ≠ authority — an artist on an account's roster (account_artist_ids) or in an org grants read/analytics only.
  • Connections are scoped per (account, artist), or per (org, artist) when org-shared — keyed on the join row, never on the bare canonical artist. Whoever establishes a connection owns it; roster membership never inherits it.
  • Authorize / execute / disconnect — owning account only (or members of the owning org for org-shared); admin override is Recoup-staff (Recoup internal org admin) only.
  • Artists stay canonical/shared; isolation lives on the connection.

Changes

  • New concept page connectors/ownership.mdx (Connectors tab → Concepts group in docs.json).
  • The page explicitly flags that the current connector endpoint reference (account-scoped) describes pre-contract shipped behavior and that this page is the authority contract until the re-keyed API ships. Endpoint OpenAPI descriptions were deliberately left untouched — they accurately describe what is live today.

Deliberately not documented

The open design decision (join-row id vs (owner, artist) pair in request/response shapes) is intentionally omitted — the api re-key PR is not designed yet. This page stays at the ownership/authority-model level.

🤖 Generated with Claude Code

Summary by cubic

Adds a concept doc that defines connector connection ownership and act-as-artist authority for the P1 re-key. Connections are owned per (account, artist) or (org, artist); roster is read/analytics only; only the owner/owning org can authorize, execute, or disconnect (Recoup staff override only).

  • Migration
    • This page is the source of truth until the re-keyed API ships.
    • Current endpoint docs remain account-scoped; re-keyed request/response shapes are TBD.
    • No production behavior change in this PR (contract-first docs only).