# 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](https://docs.gorunner.io/api/authentication#scopes) with the **Write** permission for connections (`connection:write`).

## Parameters

### Path

- `id` · Required · 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](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft) with `connectionId` and `returnUrl`. `redirectUri` here is the address to register with the service.

## Responses

- 200 OK

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

- 400 `VALIDATION_ERROR`

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

- 403 `FORBIDDEN`

  The token lacks the **Write** permission for connections.

- 403 `BROWSER_REQUIRED`

  An API token or an AI app. A token signs a connection in again with [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft), `connectionId` and `returnUrl`.

- 403 `ACCOUNT_SUSPENDED`

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

- 403 `MANAGED_CONNECTION`

  The partner manages this connection and signs it in.

- 403 `PIECE_NOT_ALLOWED`

  This workspace may not use the connection’s app.

- 404 `NOT_FOUND`

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

- 409 `ACCOUNT_DELETED`

  The workspace’s account was deleted.

- 422 `VALIDATION_ERROR`

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

- 500 `INTERNAL_ERROR`

  Something failed on GoRunner’s side. Try again.

- 503 `UNAVAILABLE`

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

- 503 `STATE_UNAVAILABLE`

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

- 503 `PIECES_UNAVAILABLE`

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

Any call can also answer: [`401 UNAUTHORIZED`](https://docs.gorunner.io/errors#UNAUTHORIZED) · [`401 TOKEN_ENDED`](https://docs.gorunner.io/errors#TOKEN_ENDED) · [`403 TOKEN_SURFACE_OFF`](https://docs.gorunner.io/errors#TOKEN_SURFACE_OFF) · [`403 FEATURE_OFF`](https://docs.gorunner.io/errors#FEATURE_OFF) · [`403 EMBED_NOT_ALLOWED`](https://docs.gorunner.io/errors#EMBED_NOT_ALLOWED) · [`403 EMBED_NOT_AVAILABLE`](https://docs.gorunner.io/errors#EMBED_NOT_AVAILABLE) · [`413 PAYLOAD_TOO_LARGE`](https://docs.gorunner.io/errors#PAYLOAD_TOO_LARGE) · [`415 INVALID_CONTENT_TYPE`](https://docs.gorunner.io/errors#INVALID_CONTENT_TYPE) · [`429 RATE_LIMITED`](https://docs.gorunner.io/errors#RATE_LIMITED) · [`503 BUSY`](https://docs.gorunner.io/errors#BUSY) · [`503 PAUSED`](https://docs.gorunner.io/errors#PAUSED) · [`503 SERVICE_UNAVAILABLE`](https://docs.gorunner.io/errors#SERVICE_UNAVAILABLE). See [Errors](https://docs.gorunner.io/api/errors#by-status).

Request

**curl**

```bash
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"
```

**JavaScript**

```js
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}/oauth2/start`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();
```

**Python**

```python
import os, requests

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

res = requests.post(
    f"{GORUNNER}/api/connections/{CONNECTION_ID}/"
    f"oauth2/start",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]
```

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

- `data` · object
  - `attemptId` · string: Names this sign-in in the launch handshake and in the status route.
  - `launchUrl` · URL: 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.
  - `bindSecret` · string: Single-use. Give it only to the popup, by postMessage to `apiOrigin`, when it asks. Never put it in a URL or storage.
  - `apiOrigin` · string: The exact origin the launch and result pages are served on. Accept messages only from the popup AND this origin.
  - `provider` · string: The provider key of the app’s declared authorize URL (`google`, `github`, …); empty for the generic `oauth2` app.
  - `redirectUri` · URL: 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.
  - `expiresAt` · time: When this attempt stops being usable (15 minutes after the press).
  - `mode` · string: How the window asked to sign in: `tab` is opened with `POST /api/connections/oauth2/attempts/{attemptId}/go`. One of `popup`, `tab`.

Related: [Start a sign-in for a new connection](https://docs.gorunner.io/api/connections/start-connection-oauth2-draft) · [Set up Google sign-in for connections](https://docs.gorunner.io/self-host/oauth-apps)

Source: https://docs.gorunner.io/api/connections/start-connection-oauth2