GoRunner

Verify a connection's credentials against the provider

Requires scope connection:write
POST
/api/connections/{id}/test

Asks a WORKER to run the piece's own connection test against the real third-party service, then records the verdict on the row (status + lastTestedAt). The API executes no piece code: only the connection id travels to the worker, which decrypts the credential itself. Takes NO request body.

READ THE BODY, NOT THE STATUS CODE. Success, provider rejection and "no worker available" are ALL delivered as HTTP 200. Branch on data.success and data.unverified. The only non-200 answers are 400/401/403/404 (bad id, auth, unknown connection) and 500 (the worker's reply could not be decoded).

Three meaningful outcomes:

  • {"success": true} (optionally with message) — the provider accepted the credentials; the row is set to active.
  • {"success": true, "unverified": true, "message": "..."} — the piece cannot be verified without running a real step, so NOTHING was proven. The row is set to unverified. Deliberately not a green pass.
  • {"success": false, "error": "..."} — either the provider refused (row becomes error, or pending for an OAuth2 connection that was never authorized), or NO WORKER was reachable. In the no-worker case the stored status is deliberately left UNCHANGED — "we could not reach a worker" is not evidence about the credentials — and error reads "No worker is available to run this right now...". The message text is the only way to tell the two apart.

The call blocks up to 30 seconds (the worker's 20s provider timeout plus the hop) and returns immediately when the fleet is known to be down.

Does NOT accept Idempotency-Key.

Authorization

bearerAuth
AuthorizationBearer <token>

An API token: Authorization: Bearer grt_…. Mint one in the app under Settings → Workspace → API tokens; the raw value is shown once. Scopes confine the token — see x-permission on each operation.

In: header

Path Parameters

id*string

The connection's UUID.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/connections/497f6eca-6276-4993-bfeb-53cbbbba6f08/test"

{  "data": {    "success": true,    "message": "Connected as gorunner-bot"  }}