Verify a connection's credentials against the provider
connection:writeAsks 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 withmessage) — the provider accepted the credentials; the row is set toactive.{"success": true, "unverified": true, "message": "..."}— the piece cannot be verified without running a real step, so NOTHING was proven. The row is set tounverified. Deliberately not a green pass.{"success": false, "error": "..."}— either the provider refused (row becomeserror, orpendingfor 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 — anderrorreads "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 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
The connection's UUID.
uuidResponse 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" }}