docs(connectors): connection ownership + act-as-artist authority contract#271
Conversation
…ract Documents the connector connection-ownership and authority model decided in recoupable/chat#1860: association grants read/analytics only, connections are scoped per (account, artist) or (org, artist) join row, and authorize/execute/disconnect authority stays with the owning account or org (Recoup-staff admin override only). Contract-first PR of the P1 re-key chain (docs -> database -> api). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
|
Warning Review limit reached
Next review available in: 45 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="connectors/ownership.mdx">
<violation number="1" location="connectors/ownership.mdx:50">
P1: The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| | Capability | Who has it | | ||
| |------------|-----------| | ||
| | Read / analytics on an artist | Any account or org member with the artist in their roster | | ||
| | Authorize a new connection | The account (or org member, for org-shared) establishing the connection — they become the owner | |
There was a problem hiding this comment.
P1: The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At connectors/ownership.mdx, line 50:
<comment>The authority matrix is ambiguous about who owns an org-shared connection. The text says an org member establishing a connection becomes 'the owner,' but for org-shared connections the scope is (organization, artist), and execute/disconnect rights go to members of the owning org — implying the org, not the individual member, should be the owner. Clarifying whether the org member acts on behalf of the org (and the org becomes the owner) would remove this ambiguity for downstream implementers.</comment>
<file context>
@@ -0,0 +1,65 @@
+| Capability | Who has it |
+|------------|-----------|
+| Read / analytics on an artist | Any account or org member with the artist in their roster |
+| Authorize a new connection | The account (or org member, for org-shared) establishing the connection — they become the owner |
+| Execute actions through a connection | The owning account only; for org-shared connections, members of the owning org |
+| Disconnect a connection | The owning account only; for org-shared connections, members of the owning org |
</file context>
Local preview verification — Mintlify
|
| Check | Result |
|---|---|
| Dev server boots, no build/MDX errors | ✅ (console clean apart from the Socket.io hot-reload notice) |
New page renders GET /connectors/ownership |
✅ HTTP 200, title "Connection Ownership - Recoup" |
docs.json nav wiring |
✅ new Concepts group with Connection Ownership, sitting above the existing Connectors group in the Connectors tab |
| Frontmatter (title + description) | ✅ renders as H1 + subtitle |
| Mintlify components | ✅ <Warning> and <Note> callouts + both Markdown tables render |
| TOC ("On this page") anchors | ✅ all five sections incl. the ≠ heading anchor |
Internal links → /api-reference/connectors/list |
✅ resolve (2 links: "Connectors API reference", "Connectors endpoint reference") |
| Sibling pages still build | ✅ / and /api-reference/connectors/list both HTTP 200 |
Contract ↔ live-behavior reconciliation
The page's authority model matches what I verified live on the merged P0b cut (api#772): roster/association = read/analytics only, and authorize/execute/disconnect are owner-scoped (a roster-only account got 403 on all three). The page also correctly flags that the current endpoint reference stays account-scoped and is the pre-contract shipped behavior — consistent with the endpoints as they run today. No drift.
Screenshots (local mint dev)
Full page — sidebar Concepts group, both tables, Warning/Note callouts, TOC:
Top / navigation — the new Concepts → Connection Ownership entry above Connectors:
Verdict
Renders cleanly, nav is wired, content is accurate and reconciles with live API behavior. No issues found. Contract-first docs only — no runtime/API change in this PR.
Screenshots hosted on a throwaway branch screenshots/pr-271-verification (deletable after review); not part of this PR.
🤖 Generated with Claude Code
Rewrite em-dash clauses as natural punctuation (periods, colons, commas, parentheses) so the copy doesn't read as machine-written. No content change. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
1 participant
Summary
Contract-first PR of the P1 connector re-key chain for recoupable/chat#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):
account_artist_ids) or in an org grants read/analytics only.Changes
connectors/ownership.mdx(Connectors tab → Concepts group indocs.json).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).Written for commit 125cdbb. Summary will update on new commits.