Third-party apps and connector requirements
Define authentication, mapping, side effects, errors and connection lifecycle.
Catalog, configuration and authorization differ
The current implementation distinguishes connectable, disabled, unconfigured, check-required and unavailable states. Verify provider setup, personal or organization account authorization, and task tool grants separately. Source includes a read-only Gmail configuration path, not proof that it is enabled in every deployment or that similar apps are integrated.
Describe the connector
Connector documentation should explain access, side effects, runtime and disabling. These are suggested documentation fields, not an importable product manifest.
| Item | Contents |
|---|---|
| Identity and version | Identifier, maintainer, compatibility and contact |
| Authentication | OAuth/key method, scopes, expiry and revocation |
| Capabilities | Tool names, input/output, read/write behavior and approval |
| Data | Mapping, timezone, pagination, retention and model exposure |
| Operations | Limits, timeouts, idempotency, health and recovery |
Keep credentials in controlled configuration
Show connection state and redacted identifiers; never put keys in task prose, knowledge or app manifests. Configure OAuth scopes and callbacks per provider requirements, and revalidate after renewal, expiry, revocation or changes. The provider setup includes draft, check and publication steps; format validation is not account authorization.
Validate reads and writes separately
Verify one read-only object for fields, pagination, date range and completeness. Write tools need explicit targets, previews, approvers, duplicate handling and provider receipts. Revalidate queued actions before execution after third-party access changes.
Handle provider uncertainty
Back off according to rate-limit hints and cap retries. Query the original operation after a timeout before repeating creation or sending. Report schema changes, truncated pagination and missing access explicitly. Mark capture time and completeness so partial data is not treated as a full business record.
Release and disable a connector
Deliver tests, authorization records, versions, runbook and rollback steps. Name account and adapter owners after launch. On disabling, stop new calls, reconcile pending work, revoke credentials and clean caches and test copies as agreed. Document compatibility changes for the project owner.