Rename or update a connection

PUT/api/connections/{id}

Renames a connection, or changes its details.

Needs an API token with the Write permission for connections (connection:write).

Parameters

Path

idRequired · UUID: The connection’s ID.

Body

nameOptional · string: Up to 255 characters, trimmed, not blank. Needed when there is no config.
configOptional · object: Left out: only a rename, and the details stay. Sent: merged over the saved ones. A field left out or blank keeps its value; null removes it.
testOptional · boolean: true tests the merged details first and saves only if the service accepts them.

What are the rarely used parameters?

authTypeOptional · string: Up to 50 characters. Empty or left out keeps it.
oauthAppOptional · string: Only with sign-in tokens in config that came from the installation’s app: installation.

Secrets follow their address

A blank secret keeps its saved value only while the connection still points at the same place. Change a host, port, database, address or connection string, and send every saved secret again; otherwise you get 422 SECRETS_REQUIRED.

Any change to config clears the last test and error, and sets status to active (pending for a sign-in with no token). pieceId can’t change: make a new connection.

Sign-in tokens from elsewhere can be saved here as in Create a connection.

Responses

200OK
Updated. The answer holds no secret.
400VALIDATION_ERROR
id isn’t a UUID, the body isn’t JSON, the name is missing or blank, authType is over 50 characters, or the change leaves a required field empty (details.fields).
403FORBIDDEN
The token lacks the Write permission for connections.
403MANAGED_CONNECTION
The partner manages this connection through its own API, so it can’t be changed here.
404NOT_FOUND
No connection with this ID in the token’s workspace.
422SECRETS_REQUIRED
The change moves where the connection points (a host, server, port, database, address or connection string) and left a saved secret blank. details.fields names the secrets to send again. Nothing changed.
422CONNECTION_TEST_FAILED
With test: true: the service refused the details (details.cause). Nothing was saved.
500INTERNAL_ERROR
Nothing changed. Try again.
503NO_VERDICT
With test: true: no answer came back (details.reason: no_worker, timeout or not_served). Nothing was saved.
503UNAVAILABLE
The installation’s OAuth app for the service (oauthApp: "installation") couldn’t be read. Nothing was saved. 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
CONNECTION_ID="your-connection-id"

curl -X PUT "$GORUNNER/api/connections/$CONNECTION_ID" \
  -H "Authorization: Bearer $GORUNNER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "host": "db2.bakery.example",
      "password": "…"
    },
    "test": true
  }'

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const CONNECTION_ID = process.env.CONNECTION_ID;

const res = await fetch(
  `${GORUNNER}/api/connections/${CONNECTION_ID}`,
  {
    method: "PUT",
    headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
    body: JSON.stringify({
        config: {
          host: "db2.bakery.example",
          password: "…",
        },
        test: true,
      }),
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
CONNECTION_ID = os.environ["CONNECTION_ID"]

res = requests.put(
    f"{GORUNNER}/api/connections/{CONNECTION_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
      "config": {
        "host": "db2.bakery.example",
        "password": "…",
      },
      "test": True,
    },
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": {
    "id": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
    "pieceId": "postgres",
    "name": "Warehouse database",
    "authType": "custom",
    "status": "active",
    "lastTestedAt": "2026-10-25T09:00:00Z",
    "account": "warehouse@db2.bakery.example:5432/orders",
    "workspaceId": "c41a7e02-9b3d-4f6a-8e15-7d2c0b9a4f68",
    "orgId": "e9d2b6f1-3a7c-4d05-b8e4-1c6f2a9d7b30",
    "createdBy": "5d8e1f3a-0b6c-4e2d-9f7a-1c3b5e8d2a40",
    "createdAt": "2026-10-20T08:00:00Z",
    "updatedAt": "2026-10-24T16:00:00Z"
  }
}

Every field

Body

nameOptional · string

New label; trimmed; blank is a 400; at most 255 characters. Optional when config is sent (absent keeps the stored name); required otherwise.

authTypeOptional · string

Optional, at most 50 characters. An empty string or omission leaves the stored value unchanged.

configOptional · object

OPTIONAL, and its ABSENCE (null reads as absent) is the signal for a rename-only update (the verdict is kept). Sent, it is MERGED over the stored config: a key left out, or a string left blank, keeps the saved value; null removes a key; anything else replaces it. A sign-in’s tokens are kept unless named. Any config change resets the verdict: status active (or pending for a sign-in with no token), lastTestedAt and lastError cleared, account recomputed. A change that moves a where field (host, server, port, database, a URL, a connection string) must send every stored secret again, else 422 SECRETS_REQUIRED (details.fields names their keys, details.changed the where keys).

testOptional · boolean

Test the merged config first, as on create: refused → 422 CONNECTION_TEST_FAILED, no verdict → 503 NO_VERDICT, nothing changed.

oauthAppOptional · string

Only with OAuth2 tokens in config (an accessToken): they came from the installation’s app for this service, which refreshes them. Refused without tokens, with clientId in config, or when the installation has no app for the service.

One of installation.

Response · 200 OK

dataobject

A stored credential set for one app. The encrypted credential itself is never present in this object — the model tags it json:"-" — so there is no field here, and no endpoint anywhere, that returns a secret you wrote.

idUUID

The connection’s id. This is the value a workflow step or trigger carries as connectionId to use these credentials.

pieceIdstring

The app these credentials belong to (e.g. seatable, postgres, googlesheets, or the generic oauth2). Fixed at creation and not changeable.

namestring

Human label. Not unique.

authTypestring

Free-text label recording the auth shape. Defaults to api_key when not supplied at creation. Conventionally one of the app’s auth.type values, but NOT validated against the app — treat it as advisory.

statusstring

The last known verdict on these credentials. active = created normally, or the last test passed. pending = an OAuth2 connection that has not completed the authorization flow (no access token yet). unverified = the last test proved nothing because the app has no connection test; credentials are checked on first real use. error = the last test was refused by the provider. expired = a refresh was refused for good — the provider rejected the stored grant or the client (revoked, aged out), or the OAuth app that issued the tokens was replaced or removed; signing in again (Re-authorize) mends it. The test endpoint (and test: true on create or update), the OAuth2 sign-in and a refused refresh set it; an update that sends config resets it to active (pending for a sign-in with no token); a rename leaves it.

One of active, pending, unverified, error, expired.

lastTestedAttime

When the connection was last tested. Absent if never tested.

tokenExpiresAttime

OAuth2 access-token expiry, when known. Refresh happens automatically at run time; there is no manual refresh call.

refreshableboolean

The stored config carries a refresh token, so tokenExpiresAt is when the access token is next RENEWED (on use), not when the connection ends. False for pasted access tokens and API keys. A connection whose refresh the provider refuses for good is marked status: expired on the next refresh attempt and needs signing in again.

managedBystring

Present only on a connection the installation’s partner manages through the embed API. It is read-only here: update, delete and the OAuth2 sign-in answer 403 MANAGED_CONNECTION; test and replace stay open.

One of partner.

workspaceIdUUID

Owning workspace. Populated on the create’s answer; the all-zero UUID on the list, the single read and an update’s answer, which read the row the way the list does and do not select it.

orgIdUUID

Owning organization. Same caveat as workspaceId: all-zero except in the create’s answer.

createdByUUID

The user who created it. Absent when no person did (the partner’s, a machine’s, rows from before creators were recorded).

createdAttime

updatedAttime

accountstring

Who or what the credential is, never a secret: the Google address a test names, user@host (with port and database) from a typed credential’s non-secret fields, a SeaTable base’s name and server. Shown to every reader. Absent until known.

createdByNamestring

The creator’s name (else their address), only while they are a member of the organization.

createdByMemberboolean

False once the creator is no longer a member of the organization. Absent with createdBy.

lastErrorobject

The last failure that still stands. Written by a failed test, a refused refresh (expired), and a run’s or poll’s definite refusal; a run’s 403 is kept as news (cause: forbidden) without changing status. Cleared by a working test, a sign-in, a config change, and the next run or poll that uses the connection and works.

attime

sourcestring

One of test, run, trigger, refresh, signin.

causestring

refused — the service refused the credential (401, SMTP 535, Postgres 28P01, MySQL 1045, …); expired — a refresh was refused for good; server — the server could not be reached; forbidden — a 403, news only; other.

One of refused, expired, server, forbidden, other.

messagestring

The service’s own words, masked of the step’s secrets, at most 1,000 characters.

runIdUUID

workflowIdUUID

workflowNamestring

While the workflow exists.

lastUseobject

The newest use the audit trail records (its connection.decrypt rows). Absent when the trail has none.

attime

kindstring

One of run, trigger, test, editor, signin.

runIdUUID

workflowIdUUID

workflowNamestring

byNamestring

The person, for a test, the builder or a sign-in, while a member of the organization.

oauthClientstring

For a connection that signs in: managed — the installation’s app; byo — its own client id; pasted — an access token with no refresh token, which cannot renew itself.

One of managed, byo, pasted.

lastSignInAttime

When a sign-in last stored tokens.

expiresAttime

When the connection stops working with no way to renew: tokenExpiresAt of a connection that is not refreshable. Absent for a refreshable one and when unknown.

testobject

Only on the answer of a create or a change sent with test: true: the test that let it be saved.

successboolean

Always true here: a refused test saves nothing and is a 422.

messagestring

The app’s own words.

unverifiedboolean

Present and true when the app cannot be tested without running a real step: saved, and nothing was proven.

Rename or update a connection

Parameters

Path

Body

Secrets follow their address

Responses

Body

Response · 200 OK

Panel