GoRunner docs
Search or askSearch⌘K

Your customers’ connections

Customers connect the services their workflows use. You choose whose name the sign-in shows, and can manage connections for them.

Embed · Self-hosted with an Embed license

A connection is a customer’s sign-in to one service, such as their Google account. It lives in their account, encrypted with the account’s own key.

How customers connect

Customers connect on Connections, from a step’s settings, or while using a template, always through the same dialog. Your page can open it with the SDK’s connect().

For a service that signs in, such as Gmail, the provider’s sign-in opens in a popup, in the same click. When it finishes, a short page in your branding says so and closes. The sign-in is tied to the window that started it.

What if my page is itself in a sandboxed frame?

That sandbox needs allow-popups and allow-popups-to-escape-sandbox, or the sign-in window can’t open. The embed’s own frame has both.

Show your name on the sign-in

The provider’s consent screen names the app that asks. Register your own, and customers see your name there, not GoRunner’s.

  1. Open Platform › OAuth apps and copy the Redirect address.
  2. In the provider’s developer console, make an OAuth app and register that redirect address. For the apps GoRunner ships, that is Google.
  3. Back on OAuth apps, press Set up… on the provider’s row.
  4. Enter the Client ID and Client secret, and save with your two-factor code.

You should see the row says Set here. New sign-ins use your app at once.

OAuth apps is there on every installation, with or without a license. The name comes from what you registered with the provider; Branding doesn’t change it. An app set here takes over from one in the server’s settings (OAUTH_MANAGED_<PROVIDER>_CLIENT_ID and _SECRET), which stays as the fallback. With neither, customers can’t connect that service, and connect() is refused with not_configured.

What happens to connections when I change the app?

Each connection remembers the app that signed it in. A new secret for the same app changes nothing.

A different app, or removing it, leaves those connections working until they next refresh. Then they need signing in again. The dialog says how many first: “This is a different app. Its 3 connections stop refreshing.”

Connect from your own button

Your app can start a sign-in itself, with no GoRunner screen. The connection is the customer’s, as if they made it in the embed.

  1. Your server calls Start a connection sign-in from your own button. It answers an authorizeUrl.
  2. Your page sends the customer’s browser there. The link works once, within 10 minutes.
  3. The provider sends them back to your returnUrl with status=connected and the connectionId, or status=error and a reason.
bash
curl -X POST \
  "$GORUNNER/api/embed/v1/accounts/acct-bakery/connections/oauth2/start" \
  -H "Authorization: Bearer $GORUNNER_EMBED_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceId": "gmail",
    "name": "Bakery Gmail",
    "returnUrl": "https://app.example.com/connections/done"
  }'

The returnUrl must be an https address (http only for localhost) on exactly one of your allowed websites or the account’s own; a wildcard allows none. Otherwise the call answers 422 RETURN_URL_NOT_ALLOWED. To read the outcome from your server, use Check how a connection sign-in ended.

Manage a connection for a customer

For a credential the customer shouldn’t handle, such as your own API’s key for their account, your server makes the connection with Create or replace a managed connection. Its values are write-only: no answer ever returns them.

The customer sees
“Managed by” your company name, or “your administrator” when Branding sets none.
They can
Use it in their workflows, and test it. They can’t rename it, sign it in again or delete it.
You can
Replace it with the same call, or delete it while no live workflow uses it.

Who can change connections

Editors add, change and remove connections. Viewers and operators see them. Switch createConnections off and nobody in the account can: they use the ones you made.

Your page hears connection.created and connection.removed as events. Your server can hear every change, and a connection the service stopped accepting, as notifications.

Checked against 12d85b3b