Project Connections

Project Connections link customer-owned mail or drive resources to one Chab project. Each connection has a globally allocated numeric Chab connection ID, but access to that ID is always limited by the current team, project, API key, and exact capability.

Drive connections use redirect authorization followed by an explicit source picker. Choose one My Drive, shared drive, OneDrive, SharePoint document library, or Dropbox space and give it a case-insensitively unique project alias of 1–120 characters. Provider account, tenant, site, and root identifiers are never used as alias fallbacks.

The provider callback must complete within the initial 10-minute authorization window. A confirmed callback opens a separate 15-minute source-selection window; viewing the picker or submitting an invalid choice does not extend it. When a provider account has more sources than the current bounded window, use Load more or refine the source-label search before selecting. Chab never puts a provider continuation token in the browser.

Initial drive consent is read-only. A connection manager can reauthorize the selected source and approve write access to enable its supported mutations. Previously granted read access does not authorize writes. Reauthorizing an existing source refreshes its current access, preserves its Chab connection ID, and cannot swap the selected root. Several project links may safely share one provider credential. Disconnecting one link does not revoke shared provider access, and provider revocation is available only after every other live link has been removed.

After the first source is linked, Add another source reuses the same valid provider authorization and opens the source picker without another OAuth prompt. Revoke provider access is shown only when the connector can revoke the provider credential and no other live project link shares it. A revoke destroys Chab's stored tokens; disconnecting alone does not.

The project page shows a safe summary to users who can view the project: connection ID, family, public connector label, an optional customer-written alias, link state, health, sync state, observation freshness, available capabilities, and a safe remediation reason. It does not show provider account IDs, tenant IDs, mailbox addresses, provider resource names, or credentials. Only users with Manage project access permission can see stewardship facts or use setup and lifecycle controls on the project's Access page.

Link, health, and sync are separate

• Link state describes the project relationship: initializing, active, disconnected, or revoked.
• Health describes whether the underlying resource can safely be used now.
• Sync describes whether projections required by a capability are ready.

An active link is not automatically usable. Chab also requires a current health observation, a current team-member steward, and the exact capability needed for the action. A stale or older-schema observation fails closed until it can be refreshed safely.

Setup and authorization

Available setup choices come from connection methods that are currently ready. If no method is ready, the Access page does not show placeholder providers. Direct connection methods ask for the eligible resource reference again when you reauthorize or reconnect. Both direct and redirect lifecycle actions reject a stale page revision instead of overwriting a newer connection change. The provider callback for redirect-based authorization expires after 10 minutes; connectors with an explicit post-callback picker may then start the separate selection window documented above. If either window expires, or your signed-in account or current team changes during the flow, Chab discards the provider response and asks you to restart. It does not retain the provider authorization code in browser history or use an arbitrary return URL.

A completed callback can be revisited safely without repeating the provider exchange. If Chab cannot determine whether a remote exchange took effect, the attempt enters recovery-required state and must not be repeated blindly. The connector can reconcile that checkpoint in the background; a confirmed result is applied once, while an outcome that is still unknown remains blocked.

Mail connections

An authorized manager can link an eligible existing team mailbox directly from the project Access page. Linking does not create a mailbox. The manager needs both Manage project access and mailbox-management permission; project membership or browser content access alone is insufficient.

Choose a mailbox and provide a non-email customer alias from 1 to 120 characters. Active mail aliases are case-insensitively unique within the project. The API exposes the alias and a provider-neutral connector label, not the mailbox address or account owner. One mailbox can be linked to multiple projects, with an independent connection ID and alias in each.

Mailbox management, browser content grants, API mail, the assistant mail pack, and Mail AI remain separate permissions and plan features. Enabling a plan's API mail flag does not enable browser mail or Mail AI, and a browser content grant does not authorize an API key. API calls additionally need an API key scope, a current project grant, the exact connection capability, and an eligible plan.

Disconnecting affects only this project link. It does not disable or delete the mailbox, revoke its provider account, remove browser grants, or change another project's link. Mailbox lifecycle, provider-grant, capability, delegated backing, and deletion changes immediately refresh or invalidate every affected project link.

Until the projects API is published, obtain project_id from the numeric identifier in the dashboard project URL. Public mail routes are documented in Mail Endpoints.

Lifecycle actions

• Connect links a new eligible resource.
• Reauthorize refreshes authorization for the same active logical source and preserves its Chab connection ID.
• Reconnect repairs a disconnected link using the same connection ID.
• Disconnect disables only this project link. It does not revoke a shared provider credential, delete provider content, or disable another project link to the same resource.
• Revoke provider credential is distinct from disconnect. Chab reserves this action for connectors that explicitly support it and refuses it while another retained project link depends on the credential.

Lifecycle changes use the revision shown by the management page. If another change wins first, refresh the page before trying again.

Stewardship

The user who establishes the connection becomes its steward. If that user leaves the team, connected-data work stops immediately and the connection shows action required. A user with Manage project access permission may explicitly claim stewardship. This does not grant project visibility, mail or drive content access, API key access, or ownership of the provider credential.

API clients should also read Authentication and API Keys, Operations, and Connected-data errors.