fix(coda): refine setup docs and verification coverage

Author: waleedlatif1

apps/docs/content/docs/search/coda.mdx

@@ -1,66 +1,64 @@
 ---
 title: Coda
-description: Index Coda pages and tables with each teammate's source permissions
+description: Connect Coda documents while preserving each teammate's access
 ---
 
-import { Callout } from 'fumadocs-ui/components/callout'
+import { Step, Steps } from 'fumadocs-ui/components/steps'
+import { Image } from '@/components/ui/image'
 
-An organization admin connects a Coda API token. Sim indexes the selected documents and matches their sharing permissions to teammates' verified Sim email addresses. Teammates do not need a personal OAuth connection for this source.
+An organization admin connects Coda once. Teammates search using their verified Sim email address; they do not need a personal Coda connection. Their email must match the address Coda reports.
 
-## Set up the source
+## Connect Coda
 
-1. In Coda, open **Account settings → API connections** and generate an API token for the account that will index your documents. Coda's current app may be labeled **Superhuman Docs**. The account must be able to read the documents and their sharing permissions.
-2. In Sim, open **Settings → Sources → Add source → Coda**. Add or select a Coda service account credential and paste the API token when prompted.
-3. Select **Documents**, or use the switch beside that field to enter **Document IDs**, separated by commas. In a Coda URL such as `https://coda.io/d/_dAbCDeFGH`, the document ID is `AbCDeFGH`. Select up to 100 documents per source. The picker shows documents the token owner can access and has opened; use IDs for other Enterprise organization documents.
-4. Leave **Enterprise organization ID** empty for ordinary token-based access. For organization-wide access, use an Enterprise organization administrator's token and enter the organization ID returned by Coda's [Admin API](https://coda.io/developers/apis/admin/v1).
-5. Select **Connect & Sync**. Open the source's **Documents** and **Sync history** to check its progress.
+<Steps>
+<Step>
 
-API tokens do not refresh automatically. When rotating a token, add the replacement credential, update the source, and verify a sync before revoking the old token. Indexing only reads Coda content; a broadly authorized token may allow other operations in Coda.
+### Create an API token
 
-## Document selection and content
+Sign in to Coda with a dedicated integration account that can read the documents and their sharing permissions. Open **Account settings → API connections → Generate API token**, name the token, and copy it. Coda's current app may be labeled **Superhuman Docs**.
 
-Explicit document IDs provide the clearest sync scope and include accessible documents the token owner has not opened. If IDs are empty, ordinary discovery includes only accessible documents the token owner has previously opened. Enterprise discovery uses the organization's document list.
+Use a standard REST API token. Do not select the MCP restriction.
 
-Discovery pages can change order while syncing. Sim therefore does not delete existing indexed content solely because it disappears from a discovery listing. Use explicit document IDs when reliable deletion reconciliation is required. Discovery runs may report incomplete reconciliation; this does not mean their returned content failed to index.
+<Image className="mx-auto h-auto w-full max-w-2xl" src="/static/search/coda-api-token.jpg" alt="Coda API connections with the Generate new token dialog" width={1280} height={720} />
 
-| Connection | Indexed content |
-| --- | --- |
-| Ordinary API token | Visible canvas page text and base tables, including all listed columns and rows. Hidden pages, embedded pages, synced pages, and duplicate table views are excluded. |
-| Enterprise organization | Page content returned by the Admin API's `LossyPlainText` format. Tables are represented only to the extent included in that export; they are not separately read through the public table API. |
+</Step>
+<Step>
 
-Comments, attachments, images, and arbitrary embedded applications are not extracted. The connector stops with an error rather than indexing truncated content when a provider response, document, or pagination limit is exceeded. If the Enterprise API omits a document revision timestamp, Sim refreshes that document on each crawl.
+### Add the source
 
-Document edits invalidate the pages and tables within that document. A full resync also refreshes rendered content whose dependencies may have changed without changing the document revision. This costs more API calls and processing than a regular sync. Ordinary unchanged documents retain their indexed content while their permissions are refreshed.
+In Sim, open **Settings → Sources → Add source → Coda**. Add or select a Coda service account credential and enter the token when prompted.
 
-## How teammate access works
+| Field | What to enter |
+|---|---|
+| Documents | Select documents, or switch to **Document IDs** and enter up to 100 IDs separated by commas. For `https://coda.io/d/_dAbCDeFGH`, the ID is `AbCDeFGH`. |
+| Enterprise organization ID | Leave blank for ordinary access. For organization-wide indexing, enter the ID from Coda's [List organizations API](https://coda.io/developers/apis/admin/v1#operation/listOrganizations) and use an Enterprise organization administrator's token. Workspace admin access alone is insufficient. |
 
-| Coda permission | Ordinary token | Enterprise organization |
-| --- | --- | --- |
-| Owner or direct email share | Matches the verified Sim email | Matches active users in the organization directory |
-| Group share | Excluded | Resolves group members through the Admin API |
-| Workspace share | Excluded | Resolves that Coda workspace's members |
-| Domain share | Excluded | Matches active organization-directory users in that exact domain |
-| Anyone with the link | Does not grant Search access | Does not grant Search access |
+The picker shows accessible documents the token owner has opened. Use IDs for other accessible documents. With no selection, Sim discovers the token owner's opened documents, or the organization's documents in Enterprise mode. Use explicit IDs when deleted documents must reliably be removed from the index; discovery listings alone are not authoritative for deletion.
+
+</Step>
+<Step>
+
+### Sync and verify
 
-Enterprise mode excludes deactivated or deleted organization users. Directly shared external guests absent from the organization directory are also excluded. A guest explicitly returned in a group's or workspace's membership can receive that group's or workspace's access, unless the organization directory marks them inactive.
+Select **Connect & Sync**. Open the source's **Documents** and **Sync history** to check indexing. Content and permission changes appear after synchronization.
 
-Ordinary token mode cannot independently check organization-level Coda account deactivation. Manage the person's Sim membership as well, or use Enterprise directory synchronization when that check is required.
+To rotate the token, add the replacement credential, update the source, and verify a sync before revoking the old token.
 
-Unknown permission types never become broad access. Sim admin status does not override Coda permissions, and a workspace API key does not inherit an individual's Coda access. A source created in **workspace access** mode inside an ordinary knowledge base intentionally shares its indexed content with that workspace; organization Search requires source permissions.
+</Step>
+</Steps>
 
-<Callout type="info">
-Permission changes take effect after synchronization. Each sync reads sharing again, including for unchanged content. If sharing or directory data cannot be completely verified, the connector fails closed through Sim's permission-sync handling. A verified Sim email must match the address Coda reports; aliases are not inferred.
-</Callout>
+## Content and access
+
+Ordinary connections index visible canvas text and base-table rows. Enterprise connections index the Admin API's plaintext page exports; tables are included only as represented in those exports. Attachments, comments, images, and remote embeds are not extracted.
+
+| Permission | Ordinary connection | Enterprise connection |
+|---|---|---|
+| Owner or direct email share | Matching verified Sim email | Matching active organization user |
+| Group, workspace, or domain share | Not expanded | Resolved through the Admin API |
+| Anyone with the link | Does not grant Search access | Does not grant Search access |
 
-## Troubleshooting
+Enterprise mode excludes deactivated and deleted users. Direct-share guests absent from the organization directory are excluded; guests explicitly listed in a group or workspace may receive that membership's access. Ordinary connections cannot check Coda organization deactivation, so manage departing users' Sim membership too.
 
-| Problem | What to check |
-| --- | --- |
-| No documents found | Open the documents as the token owner or enter their IDs explicitly. |
-| Enterprise setup fails | Confirm the account is an Enterprise organization administrator and the organization ID is correct. An ordinary workspace admin token is insufficient. |
-| Content exists but a teammate cannot search it | Check the verified Sim email, Coda share, selected scope, and sync history. Ordinary mode cannot resolve group, domain, or workspace-only shares. |
-| Cross-domain sharing is prohibited | Coda's organization policy blocks that share. Use a permitted test account or an existing workspace that permits the intended share. |
-| New document temporarily unavailable | Coda may return `409` while initializing its API snapshot. The connector retries; retry the sync if initialization takes longer. |
-| Oversized or malformed response | The sync preserves its failure state instead of treating a partial response as complete. Narrow the scope or contact your operator. |
+Sim refreshes permissions even when content is unchanged. Unverified permissions never become broad access, and Sim admin status does not override Coda sharing. For setup failures or missing results, check the token's access, Enterprise admin role if applicable, the teammate's verified email, and **Sync history**.
 
-The connector uses Coda's [public API](https://coda.io/developers/apis/v1) and optional [Enterprise Admin API](https://coda.io/developers/apis/admin/v1). It needs no additional OAuth app configuration on self-hosted Sim.
+See Coda's [public API](https://coda.io/developers/apis/v1) and [Enterprise Admin API](https://coda.io/developers/apis/admin/v1).

apps/docs/public/static/search/coda-api-token.jpg

@@ -2,10 +2,31 @@
 
 ## Precedent and authentication
 
-[Glean](https://www.glean.com/connectors/coda) supports Coda document/page search with source permissions. [Onyx's connector](https://github.com/onyx-dot-app/onyx/blob/main/backend/onyx/connectors/coda/connector.py) reads page text and table rows using a Coda API token; its content connector is not evidence that ordinary tokens expose an organization directory.
+| Reference | Verified behavior | What it establishes for Sim |
+| --- | --- | --- |
+| [Glean Coda search](https://www.glean.com/connectors/coda) | Native document/page indexing with query-time source permissions. | The same access-control objective. The public page does not specify the crawler's credentials, endpoints, directory expansion, or deletion strategy; exact implementation parity is not established. |
+| [Glean Coda agent service credential](https://docs.glean.com/administration/agent-identity/coda) | A dedicated Coda user and an MCP-restricted token for agent tools. | Dedicated identity and credential rotation are useful operational precedent. This is a separate MCP integration, not the REST indexing setup; its MCP token restriction must not be copied into Sim's connector instructions. |
+| [Onyx Coda connector](https://github.com/onyx-dot-app/onyx/blob/5fe6573c3c155e1a75b51de32d4988ee6c82164e/backend/onyx/connectors/coda/connector.py) | A bearer token, optional workspace scope, page content, and table rows through the public REST API. | Direct precedent for ordinary content ingestion. Sim uses bounded deferred hydration rather than collecting the entire source before indexing. |
+
+Onyx's [test setup](https://github.com/onyx-dot-app/onyx/blob/5fe6573c3c155e1a75b51de32d4988ee6c82164e/backend/tests/daily/connectors/coda/README.md) also uses an API token generated in account settings. Its reviewed Coda implementation has no source ACL or directory calls, and its [permission-sync registry](https://github.com/onyx-dot-app/onyx/blob/5fe6573c3c155e1a75b51de32d4988ee6c82164e/backend/ee/onyx/external_permissions/sync_params.py) has no Coda entry. It therefore does not establish Enterprise permission parity. Coda's own API documentation is the authority for Sim's Enterprise path.
 
 This connector reuses Sim's existing `coda-service-account` token credential and its selector. The metadata's `oauth` discriminator means “use a stored credential” in the shared connector framework. The actual credential is an API token, with no OAuth authorization or refresh flow. Personal credential-group enrollment is not exposed because that flow currently requires OAuth. Admin indexing matches provider-reported grants to verified Sim emails instead.
 
+## API contract audit
+
+All connector requests are GET requests authenticated with `Authorization: Bearer`. The following operation IDs were checked against the OpenAPI specifications embedded in Coda's [public reference](https://coda.io/developers/apis/v1) and [Admin reference](https://coda.io/developers/apis/admin/v1), including query parameters, response fields, pagination, and allowed formats. None of these operations is deprecated.
+
+| API | Operations used |
+| --- | --- |
+| Public identity and discovery | `whoami`, `listDocs`, `getDoc` |
+| Public content | `listPages`, `getPage`, `listPageContent`, `listTables`, `getTable`, `listColumns`, `listRows` |
+| Public permissions | `getPermissions` |
+| Admin discovery | `getOrganization`, `listDocs` with `docIds` or `docAvailabilityState` and `fetchPermissionsMode=none` |
+| Admin content and permissions | `listPagesV2`, `getPageV2` with `outputFormat=LossyPlainText`, `listDocPermissionsV2` |
+| Admin directory | `listOrgUsers`, `listGroups`, `listGroupMembers`, `listWorkspaces`, `listWorkspaceUsers` |
+
+The Admin API requires an [Enterprise organization administrator](https://help.superhuman.com/hc/en-us/articles/46210125237901-Intro-to-Superhuman-Docs-Admin-API). Ordinary workspace admin access does not satisfy that requirement. All network calls use the shared secure fetch/retry path and fixed API origins; the connector uses no browser session, private endpoint, credential impersonation, or provider permission mutation. Synthetic directory groups are Sim's internal representation of documented grants, not invented Coda API objects. Size and crawl limits below are Sim safeguards, not claimed Coda service limits.
+
 ## Access tradeoffs
 
 - Without an organization ID, only ownership and direct email grants establish individual access. Workspace, domain, group, and unknown principals are not expanded. Link possession never grants Search access. The public API does not provide organization account status; this mode cannot independently detect organization-level deactivation while a direct grant remains. Sim membership lifecycle must also be managed.

apps/sim/connectors/coda/README.md

@@ -41,6 +41,7 @@ describe('permission-scoped connector listings', () => {
   it('offers Search only for reviewed source and permission capabilities', () => {
     const search = Object.values(CONNECTOR_META_REGISTRY).filter((meta) => meta.search)
     expect(search.map((meta) => meta.id).sort()).toEqual([
+      'coda',
       'confluence',
       'github',
       'gitlab',

apps/sim/connectors/permission-scoped-listing.test.ts

@@ -49,7 +49,7 @@ const EXPECTED_COVERAGE: Record<string, string[]> = {
   'calcom-service-account': ['cal-com'],
   'claude-platform-service-account': [],
   'clickup-service-account': ['clickup'],
-  'coda-service-account': [],
+  'coda-service-account': ['coda'],
   'github-app-installation': ['github'],
   'google-service-account': [
     'gmail',

apps/sim/lib/integrations/credential-display.test.ts

@@ -86,6 +86,7 @@ describe
     let documentId: string
     let token: string
     let fixture: z.infer<typeof fixtureSchema>
+    let fixtureValidated = false
     let credentialId = generateId()
     const principal = (userId: string): Principal => ({
       kind: 'session',
@@ -173,6 +174,7 @@ describe
       ) {
         throw new Error('Refusing to change sharing on a non-fixture document')
       }
+      fixtureValidated = true
       await revokeShare()
       await waitForAcl(false)
       ids = await seedKnowledgeAclFixture()
@@ -263,7 +265,10 @@ describe
 
     afterAll(async () => {
       try {
-        if (fixture && allowSharing) await revokeShare()
+        if (fixtureValidated && allowSharing) {
+          await revokeShare()
+          await waitForAcl(false)
+        }
       } finally {
         if (ids && !uiFixturePath) {
           const rows = await db
@@ -300,7 +305,7 @@ describe
         }
         await db.$client.end()
       }
-    })
+    }, 60_000)
 
     it('indexes through admin setup and restricts private content to its owner', async () => {
       expect(metrics.embeddingCalls).toBeGreaterThan(0)