GoRunner docs
Search or askSearch⌘K

Start a sign-in for a connection

POST/api/connections/{id}/oauth2/start

For GoRunner’s own pages: signs a connection in again from a person’s browser window.

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

Parameters

Path

idRequired · UUID

The connection’s ID.

Body

Optional. Only for GoRunner’s own pages.

From code, use the other start

This start answers no sign-in link. It ties the sign-in to the window that asked, through a popup and a one-time bindSecret, so a finished link can’t be passed to someone else. API tokens are refused.

To sign a connection in again from your own code, call Start a sign-in for a new connection with connectionId and returnUrl. redirectUri here is the address to register with the service.

Responses

  • 200OK

    A sign-in tied to the browser window that asked.

  • 400VALIDATION_ERROR

    id isn’t a UUID, the body isn’t JSON, or mode or returnTo isn’t usable.

  • 403FORBIDDEN

    The token lacks the Write permission for connections.

  • 403BROWSER_REQUIRED

    An API token or an AI app. A token signs a connection in again with Start a sign-in for a new connection, connectionId and returnUrl.

  • 403ACCOUNT_SUSPENDED

    The workspace’s account is suspended. No sign-in starts.

  • 403MANAGED_CONNECTION

    The partner manages this connection and signs it in.

  • 403PIECE_NOT_ALLOWED

    This workspace may not use the connection’s app.

  • 404NOT_FOUND

    No connection with this ID in the token’s workspace.

  • 409ACCOUNT_DELETED

    The workspace’s account was deleted.

  • 422VALIDATION_ERROR

    The connection has no usable sign-in address or client ID, and the installation has no app for this service.

  • 500INTERNAL_ERROR

    Something failed on GoRunner’s side. Try again.

  • 503UNAVAILABLE

    This server can’t record sign-ins, or can’t read the installation’s app for this service, now.

  • 503STATE_UNAVAILABLE

    The account’s state couldn’t be read. Nothing started.

  • 503PIECES_UNAVAILABLE

    GoRunner couldn’t check which apps this workspace may use.

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 · 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"

URL="$GORUNNER/api/connections/$CONNECTION_ID/"
URL="${URL}oauth2/start"
curl -X POST "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

Response · 200 OK

json
{
  "data": {
    "attemptId": "Zq3XbN0iJm7dQe8TfR2wLg",
    "launchUrl": "https://api.example.com/api/oauth2/launch?attempt=Zq3XbN0iJm7dQe8TfR2wLg",
    "bindSecret": "…",
    "apiOrigin": "https://api.example.com",
    "provider": "google",
    "redirectUri": "https://api.example.com/api/oauth2/callback",
    "expiresAt": "2026-10-25T09:15:00Z",
    "mode": "popup"
  }
}
Every field

It takes no body.

Response · 200 OK

dataobject
attemptIdstring

Names this sign-in in the launch handshake and in the status route.

launchUrlURL

Point the popup opened on the click here. It is useless on its own: the page asks its opener for bindSecret and goes nowhere without it.

bindSecretstring

Single-use. Give it only to the popup, by postMessage to apiOrigin, when it asks. Never put it in a URL or storage.

apiOriginstring

The exact origin the launch and result pages are served on. Accept messages only from the popup AND this origin.

providerstring

The provider key of the app’s declared authorize URL (google, github, …); empty for the generic oauth2 app.

redirectUriURL

The callback this server is redirected back to ({PUBLIC_API_URL}/api/oauth2/callback). Register exactly this with the provider. It is a browser endpoint returning HTML; you never call it.

expiresAttime

When this attempt stops being usable (15 minutes after the press).

modestring

How the window asked to sign in: tab is opened with POST /api/connections/oauth2/attempts/{attemptId}/go.

One of popup, tab.