From 1958c15fb5498903f31f14a63ba3110bd5aa4724 Mon Sep 17 00:00:00 2001 From: Badhri Ravikumar Date: Wed, 11 Nov 2026 11:13:24 +0530 Subject: [PATCH 1/2] agents: document strict provider connection create and reconnect (MARSOHS-2480) Connection create no longer resumes an existing connection: if the actor already has an active, pending, or expired connection for the provider, it returns 409 (AR-3404). Update the create description, which still said "Creates, or resumes", document the 409, and say what reconnect does: resume a pending authorization or restart an expired or revoked connection, keeping its id, user_id and scopes. Co-Authored-By: Claude Opus 5.5 --- .../agents_create_provider_connection.yml | 17 +++++++++++++---- .../agents_reconnect_provider_connection.yml | 7 +++++-- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/specification/resources/agents/agents_create_provider_connection.yml b/specification/resources/agents/agents_create_provider_connection.yml index b5902761b..bdf5170b7 100644 --- a/specification/resources/agents/agents_create_provider_connection.yml +++ b/specification/resources/agents/agents_create_provider_connection.yml @@ -1,9 +1,11 @@ operationId: harness_create_provider_connection summary: Create a provider connection for one actor. -description: Creates, or resumes, the connection `{provider}` will use for `user_id`. `user_id` is the - actor identifier the connection acts for, not a DigitalOcean user id. A pending connection includes - an `authorization` object the user still has to complete. An active connection omits it. No token - is returned. `github` is the provider served today. +description: Creates the connection `{provider}` will use for `user_id`. `user_id` is the actor + identifier the connection acts for, not a DigitalOcean user id. Each actor has at most one connection + per provider; if `user_id` already has an active, pending, or expired connection for `{provider}`, the + request fails with `409`, and `POST /v2/agents/auth/{provider}/connections/{connection_id}/reconnect` + resumes or restarts it instead. The response includes an `authorization` object while the user still + has to complete the interactive step. No token is returned. `github` is the provider served today. tags: - Harness Runtime parameters: @@ -52,6 +54,13 @@ responses: $ref: ../../shared/responses/unauthorized.yml '404': $ref: ../../shared/responses/not_found.yml + '409': + description: '`user_id` already has an active, pending, or expired connection for `{provider}`. Reconnect it instead.' + headers: *id001 + content: + application/json: + schema: + $ref: models/definitions.yml#/error '501': description: Provider connections are not enabled. headers: *id001 diff --git a/specification/resources/agents/agents_reconnect_provider_connection.yml b/specification/resources/agents/agents_reconnect_provider_connection.yml index b0e27c85b..db7cff9b8 100644 --- a/specification/resources/agents/agents_reconnect_provider_connection.yml +++ b/specification/resources/agents/agents_reconnect_provider_connection.yml @@ -1,7 +1,10 @@ operationId: harness_post_provider_connection_reconnect summary: Start a fresh login for an existing connection. -description: Begins the interactive step again for a connection that needs it. The response includes - `authorization` while that step is outstanding. No token is returned. +description: Resumes a pending connection's authorization, or starts a new one for an expired or revoked + connection. The connection keeps its id, `user_id`, and scopes, so environments that use it keep + working once it is active again. An active connection is returned unchanged. Only the member who owns + the connection can reconnect it. The response includes `authorization` while the interactive step is + outstanding. No token is returned. tags: - Harness Runtime parameters: From 22b52db6920a2e92e5457e4be737d83b786d1321 Mon Sep 17 00:00:00 2001 From: Badhri Ravikumar Date: Thu, 12 Nov 2026 11:34:42 +0530 Subject: [PATCH 2/2] agents: address review on provider connection create and reconnect - Create: revoked connections don't count toward the one-per-actor limit; if the actor's only connection is revoked, create restarts it under the same id with the request's scopes, so delete then create is how to change scopes. Point the 409 at the list route (filtered by user_id) to find the id to reconnect. A successful create returns the connection as pending with an authorization object, and the 200 text says so. - Reconnect: a caller who doesn't own the connection gets 404, the same as for an unknown connection. Co-Authored-By: Claude Opus 5.5 --- .../agents_create_provider_connection.yml | 19 ++++++++++++------- .../agents_reconnect_provider_connection.yml | 5 +++-- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/specification/resources/agents/agents_create_provider_connection.yml b/specification/resources/agents/agents_create_provider_connection.yml index bdf5170b7..82bfbba66 100644 --- a/specification/resources/agents/agents_create_provider_connection.yml +++ b/specification/resources/agents/agents_create_provider_connection.yml @@ -1,11 +1,16 @@ operationId: harness_create_provider_connection summary: Create a provider connection for one actor. description: Creates the connection `{provider}` will use for `user_id`. `user_id` is the actor - identifier the connection acts for, not a DigitalOcean user id. Each actor has at most one connection - per provider; if `user_id` already has an active, pending, or expired connection for `{provider}`, the - request fails with `409`, and `POST /v2/agents/auth/{provider}/connections/{connection_id}/reconnect` - resumes or restarts it instead. The response includes an `authorization` object while the user still - has to complete the interactive step. No token is returned. `github` is the provider served today. + identifier the connection acts for, not a DigitalOcean user id. Each actor has at most one active, + pending, or expired connection per provider. If `user_id` already has one, the request fails with + `409`. Find that connection's id with `GET /v2/agents/auth/{provider}/connections?user_id=...`, then + resume or restart it with `POST /v2/agents/auth/{provider}/connections/{connection_id}/reconnect`, + which keeps its scopes. Revoked connections do not count toward the limit, and list responses omit + them. If the only connection `user_id` has for `{provider}` is revoked, for example by `DELETE`, + create starts it again under the same connection id, with the scopes in this request. To change a + connection's scopes, delete it and then create it. A successful create returns the connection as + `pending`, with an `authorization` object for the interactive step. No token is returned. `github` + is the provider served today. tags: - Harness Runtime parameters: @@ -25,7 +30,7 @@ requestBody: $ref: models/definitions.yml#/create_provider_connection_request responses: '200': - description: The connection, plus authorization steps when it is still pending. + description: The new connection, `pending`, with the authorization steps the user has to complete. headers: ratelimit-limit: $ref: ../../shared/headers.yml#/ratelimit-limit @@ -55,7 +60,7 @@ responses: '404': $ref: ../../shared/responses/not_found.yml '409': - description: '`user_id` already has an active, pending, or expired connection for `{provider}`. Reconnect it instead.' + description: '`user_id` already has an active, pending, or expired connection for `{provider}`. List the connections filtered by `user_id` to find its id, then reconnect it.' headers: *id001 content: application/json: diff --git a/specification/resources/agents/agents_reconnect_provider_connection.yml b/specification/resources/agents/agents_reconnect_provider_connection.yml index db7cff9b8..4454812c5 100644 --- a/specification/resources/agents/agents_reconnect_provider_connection.yml +++ b/specification/resources/agents/agents_reconnect_provider_connection.yml @@ -3,8 +3,9 @@ summary: Start a fresh login for an existing connection. description: Resumes a pending connection's authorization, or starts a new one for an expired or revoked connection. The connection keeps its id, `user_id`, and scopes, so environments that use it keep working once it is active again. An active connection is returned unchanged. Only the member who owns - the connection can reconnect it. The response includes `authorization` while the interactive step is - outstanding. No token is returned. + the connection can reconnect it; for anyone else the response is `404`, the same as for an unknown + connection. The response includes `authorization` while the interactive step is outstanding. No token + is returned. tags: - Harness Runtime parameters: