GoRunner docs
Search or askSearch⌘K

Create or replace a managed connection

PUT/api/embed/v1/accounts/{accountId}/connections/{connectionKey}

Saves a connection you manage for a customer, by your key: made the first time, replaced after.

Needs a partner key: Authorization: Bearer gre_…, from Platform › Partner keys. Call it from your server only.

Embed · Self-hosted with an Embed license

Parameters

Path

accountIdRequired · string

Your ID for the customer’s account: 1 to 255 bytes of UTF-8, case-sensitive. URL-encode it: it may contain /.

connectionKeyRequired · string

Your key for the connection: 1 to 255 bytes, unique in its workspace. URL-encode it.

Body

nameRequired · string

1 to 200 characters, no control or invisible characters.

pieceIdRequired · string

The app, such as googlesheets. It can’t change: delete the key first.

valuesRequired · object

The details, by the app’s own field names. Never answered back. For a sign-in app: accessToken, refreshToken, expiresAt (RFC 3339), tokenType, and the app that issued them.

workspaceIdOptional · string

The workspace, by your ID. Left out: the default workspace.

What are the rarely used parameters?
authTypeOptional · string

One the app declares. Left out: the app’s own.

oauthAppOptional · string

installation: the tokens came from the installation’s app for this service, which renews them. Not with clientId in values.

What the customer can do with it

Use it in their workflows, but not change, sign in again or delete it. In their product it reads MANAGED_CONNECTION if they try.

Every field is checked before anything is written. Each required field must be given; an app whose fields are all optional needs at least one. Tokens from your own app also need its clientId and clientSecret to renew. See Your customers’ connections.

Responses

  • 200OK

    Replaced.

  • 201Created

    Created.

  • 400VALIDATION_ERROR

    An unknown app, a missing or malformed value, a field the app doesn’t have (named in details.field, with the app’s details.fields), an authType it doesn’t declare, or oauthApp where the installation has no app.

  • 403PIECE_NOT_ALLOWED

    This account may not use the app.

  • 404NOT_FOUND

    No such account or workspace.

  • 409ACCOUNT_DELETED

    The account is deleted. Restore it first, within 30 days.

  • 409CONFLICT

    The key already names a connection of another app.

  • 500INTERNAL_ERROR

    Something failed on the installation’s side. Try again.

  • 503PIECES_UNAVAILABLE

    The apps the account may use couldn’t be read. Nothing was written. Try again.

Any call can also answer: 401 UNAUTHORIZED · 403 EMBED_NOT_LICENSED · 403 IP_NOT_ALLOWED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY. See Errors.

Request

GORUNNER="https://automations.example.com"
GORUNNER_EMBED_KEY="YOUR_PARTNER_KEY"  # gre_…
ACCOUNT_ID="acct-bakery"
CONNECTION_KEY="sheets-main"

URL="$GORUNNER/api/embed/v1/accounts/$ACCOUNT_ID/"
URL="${URL}connections/$CONNECTION_KEY"
curl -X PUT "$URL" \
  -H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Google Sheets (Bakery)",
    "pieceId": "googlesheets",
    "values": {
      "accessToken": "ya29.…",
      "refreshToken": "1//…",
      "expiresAt": "2026-10-25T10:00:00Z"
    },
    "oauthApp": "installation"
  }'

Response · 201 Created

json
{
  "data": {
    "key": "sheets-main",
    "id": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b",
    "name": "Google Sheets (Bakery)",
    "pieceId": "googlesheets",
    "status": "ok",
    "managedBy": "partner",
    "workspace": {
      "id": null,
      "default": true
    },
    "createdAt": "2026-10-20T08:00:00Z",
    "updatedAt": "2026-10-25T09:00:00Z"
  }
}
Every field

Body

pieceIdRequired · string
nameRequired · string

1–200 characters, the rule every name the partner gives follows: no control or invisible formatting characters.

workspaceIdOptional · string

Omitted = the account’s default workspace (default names it too); the empty value is refused.

authTypeOptional · string

One the app declares; omitted = the app’s own.

valuesRequired · object

The credential. Write-only. An app’s own auth fields: every value as text, even a number or a yes/no ("587", "true"; anything else is 400 naming it, as is a required one left out); a key the app does not have is 400 VALIDATION_ERROR naming it in details.field (values.<key>), with details.unknown and the app’s own details.fields; an app whose fields are all optional needs at least one. Or, for an app that signs in with OAuth2: accessToken (required), refreshToken, expiresAt (RFC 3339), tokenType, and — with a refresh token — the client that issued it: clientId/clientSecret, or oauthApp. Other keys are ignored for an OAuth2 app.

oauthAppOptional · string

The OAuth2 tokens came from the installation’s app for this service: its client id is recorded, and every refresh uses that client. Refused when the installation has no app for the service, or with clientId in values.

One of installation.

Response · 200 OK, 201 Created

dataobject

Never carries a secret.

keystring or null

The partner’s key; null for one the customer made.

idUUID
namestring
pieceIdstring
statusstring

expired: its tokens can no longer be refreshed; replace them.

One of ok, error, expired.

managedBystring

One of partner, customer.

workspaceobject
idstring or null

The partner’s workspace id; null for the default workspace.

defaultboolean
createdAttime
updatedAttime