> ## Documentation Index
> Fetch the complete documentation index at: https://editor.pascal.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Connect workspace accounts to Pascal, use their resources in chat and Files, or build a provider adapter.

Connectors bring external resources into a **workspace**. Plugins add scene elements and behavior to a **project**. An app that calls Pascal uses the existing API or MCP authentication; an outgoing connector does not authorize incoming clients.

## Connect an account

Open **Workspace → Connectors**. The directory shows connected services first, with the remaining services below. Choose Google Drive, OneDrive, Dropbox, Pinterest or GitHub and continue to the provider to authorize an account. Pascal supplies supported read permissions; there are no resource checklists, connection names or project selectors. The account is available across current and future workspace projects under its privacy settings.

> [!NOTE]
>
> Google Drive is currently limited to invited testers while restricted-scope approval remains outstanding. Pinterest currently supports business accounts; personal-account data may be refused until Pinterest grants separate access. These limits appear before connection, and a provider-review refusal does not require reconnecting.

The service's account page shows health and direct reconnect, sharing and disconnect actions. Choose **Connect another account** to add another identity. Each keeps separate credentials. An unavailable registration reports a configuration issue rather than offering sample data.

* **Private:** other members can see who connected the service, but not its private account label, files or results.
* **Share with workspace:** make supported content available to current members. New accounts remain private until shared.
* **Agent access:** current read grants and privacy are checked before context enters a model. Private organization accounts must be shared before a collaborative project-agent run can use them.

The supplying member manages sharing and reconnection. Workspace administrators may disconnect accounts without gaining their contents. A departed custodian makes new live access unavailable. Connecting never grants external writes or automatically imports files.

## Use it in chat

Type **@** and choose **Connectors**, or paste/drop a supported provider link. One eligible account can resolve a source automatically. With multiple accounts for that service, mention the account to use. An unavailable explicit account never silently switches credentials. Recognizing a link does not establish read permission.

Supported Google Drive, Dropbox, OneDrive, GitHub and Pinterest links display compact inline references in drafts and message threads. Local service logos and Google product icons identify the source; authorized metadata supplies the actual file, folder, repository, Pin or board title when available. Click a draft reference to edit its full URL. Sending, copying, queueing and reopening retain the exact link. Meaningful authored Markdown labels stay intact. Metadata lookup reads no contents; names remain temporary project/account-scoped view state, and an explicit account mention selects only that message’s account.

Ask the agent to find or read a source, then explicitly save it to project or workspace Files, optionally naming a folder. Source material is bounded context; reading does not itself authorize retention.

## Import into Files

Choose **Files → Add files → From connectors**, search a permitted account and import supported content. The canonical private copy follows Pascal's project/workspace permissions and remains after source disconnection. A workspace original can be linked into a project without creating another file store.

Imports retain source identity, observed revision, representation, checksum, attribution/rights, operation receipt and verified original shared link. Chat imports also preserve authenticated actor and available turn provenance. Drive alone supports bounded recursive folder import, including empty folders; other services support the operations below.

| Service | Supported operations | Limits to expect |
| - | - | - |
| Google Drive | Account/shared-drive search; linked files/folders; Docs, Slides and bounded Sheets context; individual or bounded recursive folder imports. | Native documents import as PDF. Shortcuts are unsupported. |
| OneDrive | Current-drive search, direct children, supported text/PDF reads and individual original-file imports. | Read-only `Files.Read`; use canonical account items. Short `1drv.ms` links and general SharePoint-site discovery are unsupported. |
| Dropbox | Account filename search, listings, supported text/PDF reads and individual imports from verified account/shared sources. | Shared-folder listings are nonrecursive; children require independent account access. Protected/unverifiable links are refused. |
| Pinterest | Account Pins/public boards; `board:<words>` finds boards. Pin context, supported images or attributed Markdown snapshots; bounded board manifests. | Page-local filtering, not global image search. No secret boards or bulk board-image harvest. Visibility does not establish a license. |
| GitHub | Selected repositories through the GitHub App; repository/blob/tree links; supported text reads and individual regular-file imports at verified revisions. | Installation and user permissions both apply. No writes, symlinks, submodules or recursive folder copies. |

Per-file intake is limited to 20 MiB. Text extraction, result sizes and pagination are separately bounded. Preserve truncation and continuation indicators rather than treating one page as a complete inventory.

> [!NOTE]
>
> Real local editor-chat reads and private Files imports passed for exercised Google Drive, OneDrive, GitHub and Pinterest cases; GitHub's live proof covers one public repository. Pinterest's architectural Pin image retained its original parent Pin, source article and turn provenance, with private bytes independently verified. Dropbox connection/listing passed, but the tested account has no files and restricted team features, so file import remains unverified. Provider production approvals and deployment checks remain separate from these local tests.

## Connect an app to Pascal

For clients that send data to Pascal or receive project files, use [API & agents](https://editor.pascal.app/settings?view=api-keys), the [Pascal API](/docs/developers/api.md), or [MCP](/docs/developers/mcp.md). Use the supported file lifecycle for uploads/downloads. Account credentials stay encrypted server-side and never enter the browser, Files, prompts or frontend code.

## Build a provider adapter

Adapters are reviewed code, not arbitrary URLs installed by end users. The registry describes supported operations; the shared runtime owns identity, workspace scope, privacy, grants and provenance. All five native adapters use server-side OAuth. A managed authentication service can sit behind that boundary without replacing Pascal's authority checks.

1. Define supported resources and versioned operations, effects and result types.
2. Bind authorization to the initiating member, workspace, provider and connection. Verify the upstream subject; reconnect and refresh cannot revive revoked access or replace an identity.
3. Use fixed endpoints and validated provider URLs. Bound pagination, bytes and time; verify identity/revision around reads/imports. Preserve source links, attribution and rights without inferring a license.
4. Keep provider calls outside database transactions. Recheck identity, privacy, grants and generation before exposing or committing results. Retained files use canonical private intake.
5. Test private/shared isolation, multiple accounts, provider credential separation, departed members, revoked/reordered requests, retries and provenance. Obtain representative real-account acceptance separately.

### Operator credentials and callbacks

Registrations belong to Pascal's operator. End users authorize existing accounts; they do not create developer applications. Client secrets and tokens are server-only. Register exact local callbacks `http://localhost:3100/api/workspace/connectors/{providerId}/callback` and production callbacks `${BASE_URL}/api/workspace/connectors/{providerId}/callback`, replacing provider IDs and origin literally. `BASE_URL` means Pascal's trusted origin, normally `https://editor.pascal.app`, not a new environment variable.

| Provider ID | Server client ID / secret variables | Requested authorization |
| - | - | - |
| `google-drive` | `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | `openid email profile https://www.googleapis.com/auth/drive.readonly`; enable Drive and Sheets APIs. |
| `onedrive` | `CONNECTOR_MICROSOFT_CLIENT_ID` / `CONNECTOR_MICROSOFT_CLIENT_SECRET` | `openid profile email offline_access User.Read Files.Read`, delegated web flow. |
| `dropbox` | `CONNECTOR_DROPBOX_CLIENT_ID` / `CONNECTOR_DROPBOX_CLIENT_SECRET` | `account_info.read files.metadata.read files.content.read sharing.read`, offline Full Dropbox account access. |
| `pinterest` | `CONNECTOR_PINTEREST_CLIENT_ID` / `CONNECTOR_PINTEREST_CLIENT_SECRET` | `user_accounts:read boards:read pins:read`. |
| `github` | `CONNECTOR_GITHUB_CLIENT_ID` / `CONNECTOR_GITHUB_CLIENT_SECRET` | GitHub App read-only Contents/Metadata, installed on selected repositories; `offline_access` for expiring user tokens. |

Follow the [Google scope guidance](https://developers.google.com/workspace/drive/api/guides/api-specific-auth), [Microsoft registration guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app), [Dropbox OAuth guide](https://docs.dropboxapi.com/dropbox-api/docs/oauth), [Pinterest access tiers](https://developers.pinterest.com/docs/key-concepts/access-tiers/) and [GitHub App token guide](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens). Pinterest Trial permits reading Pins and boards with daily app-level rate limits; Pinterest recommends Standard access for production use. Public availability requires applicable provider approvals and Pascal's release checks.

Production Drive authorization admits only exact Pascal user IDs in server-only `CONNECTOR_GOOGLE_DRIVE_ALLOWED_USER_IDS` (comma-separated, closed when empty). Branding approval does not approve Drive scopes. Pinterest's separate [non-business data restriction](https://developers.pinterest.com/docs/changelog/changelog/#pinner-data-access-denial-error) can also refuse individual Pins or boards from a connected business account. Standard access alone does not remove that restriction.

### Shared client

The transport-injected client is available in the monorepo as `@pascal/api/connectors`:

```ts theme={null}
import { createWorkspaceConnectorClient } from '@pascal/api/connectors'

const connectors = createWorkspaceConnectorClient({
  baseUrl: 'https://editor.pascal.app',
  workspaceId,
  fetch: authenticatedFetch,
})
const state = await connectors.discover()

// Select a returned connection/resource with an allowed agent capability.
const receipt = await connectors.execute({
  connectionId,
  capabilityId: 'read',
  resourceId,
  query: '',
  idempotencyKey: crypto.randomUUID(),
})
```

Search with `capabilityId: 'search'` and a `query`, then read a returned resource ID. Pass `nextPageToken` unchanged as `pageToken` to continue. Source links are provider-validated; arbitrary URLs are not fetch targets. Results contain bounded context, source identity and revision.

Reuse the same idempotency key after an uncertain response; changed inputs need a new key. Live reads recheck provider access instead of replaying cached contents. Inspect receipt status and result: HTTP 200 alone is not operation success. Connector permissions do not grant scene edits, purchases, provider writes or unrestricted delegation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.