# Your customers’ connections

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

A [connection](https://docs.gorunner.io/glossary#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()`](https://docs.gorunner.io/embed/sdk#methods).

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](https://docs.gorunner.io/embed/api/connections/start-connection-sign-in). 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](https://docs.gorunner.io/embed/api/connections/get-connection-sign-in).

## 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](https://docs.gorunner.io/embed/api/connections/put-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](https://docs.gorunner.io/embed/api/connections/delete-connection) 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](https://docs.gorunner.io/embed/events). Your server can hear every change, and a connection the service stopped accepting, as [notifications](https://docs.gorunner.io/embed/notifications).

## Related

- [Connections](https://docs.gorunner.io/build/connections): What customers see on the page · 4 min
- [Templates for customers](https://docs.gorunner.io/embed/templates): Give a template your connection
- [Notifications](https://docs.gorunner.io/embed/notifications): Hear when a connection expires

Source: https://docs.gorunner.io/embed/customer-connections