From 04d156992f6750bc77e15e84c10e43c09cb190ea Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 2 Jul 2026 15:06:39 +0530 Subject: [PATCH 1/2] =?UTF-8?q?docs(changelog):=20connector=20platform=20?= =?UTF-8?q?=E2=80=94=20uniform=20API=20+=20bounded=20vendor=20calls?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New Jul 02 : the generic {provider} connector route set is now in the public API reference, unknown providers 404, and connector vendor calls are deadline-bounded. Error-codes page gains UZ-CONN-003/004 and de-GitHubs the now-generic UZ-CONN-001 wording. Co-Authored-By: Claude Opus 4.8 (1M context) --- api-reference/error-codes.mdx | 2 ++ changelog.mdx | 13 +++++++++++++ 2 files changed, 15 insertions(+) diff --git a/api-reference/error-codes.mdx b/api-reference/error-codes.mdx index 112fff8..f4f1df1 100644 --- a/api-reference/error-codes.mdx +++ b/api-reference/error-codes.mdx @@ -185,6 +185,8 @@ Codes here are the externally-observable subset of the server registry; a gap in |---|---|---|---| | `UZ-CONN-001` | 503 | Connector not configured | Connect is unavailable for this provider on this deployment — the platform app credentials (GitHub App slug / Slack app secrets) are unset. An operator must register the provider app and populate the admin vault before workspaces can connect. | | `UZ-CONN-002` | 400 | Invalid connect state | The connect callback's `state` was missing, forged, expired, or already used. Start the connect again from the dashboard — each attempt issues a fresh single-use state. | +| `UZ-CONN-003` | 502 | Connector vendor call exceeded its deadline | An outbound call to the connector's vendor hit its enforced deadline (the vendor accepted the connection, then stalled), could not be deadline-armed, or the vendor was unreachable — the call never runs unbounded. Transient — retry; if it persists, check the vendor's status page and this deployment's egress. | +| `UZ-CONN-004` | 404 | Unknown connector provider | The `{provider}` in the connector URL does not match any provider in this deployment's connector registry. List the available providers from the dashboard connectors page. | | `UZ-CRED-001` | 404 | Integration not connected | No connected integration matches this id for the fleet's workspace. Connect it first (e.g. GitHub via the dashboard **Connect** flow) before a fleet can mint a token for it. | | `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | | `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). Transient — retry shortly; if it persists, check GitHub status and the App configuration. | diff --git a/changelog.mdx b/changelog.mdx index 474af05..bff7a8c 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -42,6 +42,19 @@ export const STAGE_SELF_MANAGED_M66 = "$0.0001"; - **New error codes:** `UZ-SLK-010` (401, invalid Slack signature), `UZ-SLK-011` (401, stale timestamp), `UZ-SLK-020` (200 — an event from a team with no install is acknowledged and ignored), `UZ-SLK-022` (502, OAuth token exchange failed), `UZ-SLK-030` (502, answer delivery to Slack failed — logged and retried; the run itself never fails). `UZ-CONN-001`/`UZ-CONN-002` now cover the Slack connect flow as well as GitHub. + + ## Connector platform: one uniform API, bounded vendor calls + + Connecting a third-party service (Slack, GitHub, and the providers landing next) now runs through one uniform, documented route set instead of a per-provider one. The URLs you already use are unchanged; what's new is that the connector surface is in the public API reference, an unknown provider returns a clear `404` instead of a generic not-found, and every outbound call agentsfleet makes to a connector's vendor is now time-bounded — a vendor that accepts a connection and then stalls degrades that one connect or mention instead of tying up the platform. + + ## API reference + + - **`POST /v1/workspaces/{workspace_id}/connectors/{provider}/connect`** and **`GET /v1/workspaces/{workspace_id}/connectors/{provider}`** — start a connect and read connector status for any registered provider (`slack`, `github`), Bearer-authed with the `connector:write` / `connector:read` scopes. + - **`GET /v1/connectors/{provider}/callback`** — the vendor redirect target; Bearer-less, authenticated by the signed single-use state minted at connect. + - **`UZ-CONN-003`** (502) — an outbound call to a connector's vendor hit its enforced deadline, could not be time-bounded, or the vendor was unreachable; the call never runs unbounded. Transient — retry. + - **`UZ-CONN-004`** (404) — the `{provider}` in a connector URL matches no provider on this deployment; the body names the unknown provider. + + ## Bring your own Fleet templates From 28d8f9c689e07533f9a578bb712b0f9e703afbfd Mon Sep 17 00:00:00 2001 From: Kishore Kumar Date: Thu, 2 Jul 2026 18:32:27 +0530 Subject: [PATCH 2/2] docs(m108): add Connectors group to API reference nav Greptile flagged the connector endpoints announced in the changelog as absent from docs.json navigation. Backend agentsfleet#469 has now merged and the live OpenAPI spec carries these paths, so add the Connectors group without breaking the openapi-drift lint check. Co-Authored-By: Claude Sonnet 5 --- docs.json | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs.json b/docs.json index f1f09de..6bea421 100644 --- a/docs.json +++ b/docs.json @@ -195,6 +195,15 @@ "DELETE /v1/workspaces/{workspace_id}/credentials/{credential_name}" ] }, + { + "group": "Connectors", + "pages": [ + "POST /v1/workspaces/{workspace_id}/connectors/{provider}/connect", + "GET /v1/workspaces/{workspace_id}/connectors/{provider}", + "GET /v1/connectors/{provider}/callback", + "POST /v1/connectors/slack/events" + ] + }, { "group": "Approvals", "pages": [