Test sign-in details before saving
POST/
Tests sign-in details before you save them. Nothing is stored.
Needs an API token with the Write permission for connections (connection:write).
Parameters
Body
pieceIdOptional · stringThe app, for a new connection. Needed without
connectionId.connectionIdOptional · UUIDFor a change: a saved connection of the same app. Fields you leave blank keep its saved values.
configOptional · objectThe details to test.
Read it
success: true with account, who it signed in as. Or success: false with error, in the service’s words, and cause: refused, expired, server, forbidden or other.
noVerdict: true means no answer came back: no worker, the time ran out, or this installation doesn’t run the app (reason). Only then should a form offer to save untested.
Responses
- 200OK
The result, whatever it was. Read
successandnoVerdict. No app, an unknown app, an app other than the connection’s, or details that aren’t valid.
- 403
FORBIDDENThe token lacks the Write permission for connections.
The partner manages this connection through its own API, so it can’t be changed here.
- 404
NOT_FOUNDconnectionIdisn’t in this workspace. The change moves where the connection points (a host, server, port, database, address or connection string) and left a saved secret blank.
details.fieldsnames the secrets to send again. Nothing changed.The saved connection couldn’t be read. Try again.
Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.
Request
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…" # needs Write for connections
curl -X POST "$GORUNNER/api/connections/test" \
-H "Authorization: Bearer $GORUNNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"pieceId": "email",
"config": {
"host": "smtp.office365.com",
"port": "587",
"email": "warehouse@bakery.example",
"password": "…"
}
}'const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const res = await fetch(
`${GORUNNER}/api/connections/test`,
{
method: "POST",
headers: {
Authorization: `Bearer ${TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
pieceId: "email",
config: {
host: "smtp.office365.com",
port: "587",
email: "warehouse@bakery.example",
password: "…",
},
}),
},
);
const { data } = await res.json();import os, requests
GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
res = requests.post(
f"{GORUNNER}/api/connections/test",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"pieceId": "email",
"config": {
"host": "smtp.office365.com",
"port": "587",
"email": "warehouse@bakery.example",
"password": "…",
},
},
)
data = res.json()["data"]Response · 200 OK, refused
{
"data": {
"success": false,
"error": "smtp auth: 535 5.7.3 Authentication unsuccessful",
"cause": "refused"
}
}Every field
Body
pieceIdOptional · stringThe app, for an add. Required without
connectionId.connectionIdOptional · UUIDFor a change: the draft is laid over this connection’s stored config (a blank field keeps the saved value). Same app, same workspace.
configOptional · object
Response · 200 OK
dataobjectsuccessbooleanmessagestringaccountstringerrorstringcausestringOne of
refused,expired,server,forbidden,other.noVerdictbooleanNo verdict came back (no worker, the time ran out, an app this build does not serve): the only case a form offers to save without a test.
reasonstringOne of
no_worker,timeout,not_served.