Check a connection’s sign-in

GET/api/connections/{id}/oauth2/attempts/{attemptId}

For GoRunner’s own pages: reads how a window’s sign-in for a connection is going.

Needs an API token with the Read permission for connections (connection:read).

Parameters

Path

idRequired · UUID: The connection’s ID.
attemptIdRequired · string: The sign-in’s ID.

Who can read it

Only the person who started it. Ask every second or two while it is open; after 15 minutes it answers expired. From code, read your sign-in with Check a sign-in.

Responses

200OK
Where the sign-in stands: pending, launched, connected, failed or expired.
400VALIDATION_ERROR
id isn’t a UUID.
403FORBIDDEN
The token lacks the Read permission for connections.
404NOT_FOUND
No such sign-in for this person, workspace and connection.
500INTERNAL_ERROR
Something failed on GoRunner’s side. Try again.
503UNAVAILABLE
This server can’t read sign-ins now.

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 · 403 ACCOUNT_SUSPENDED · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for connections
CONNECTION_ID="your-connection-id"
ATTEMPT_ID="your-attempt-id"  # from the start

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

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const CONNECTION_ID = process.env.CONNECTION_ID;
const ATTEMPT_ID = process.env.ATTEMPT_ID; // from the start

const res = await fetch(
  `${GORUNNER}/api/connections/` +
    `${CONNECTION_ID}/oauth2/attempts/` +
    `${ATTEMPT_ID}`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
CONNECTION_ID = os.environ["CONNECTION_ID"]
ATTEMPT_ID = os.environ["ATTEMPT_ID"]  # from the start

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

Response · 200 OK

json

{
  "data": {
    "status": "connected",
    "connectionId": "0f8b2c7e-4a51-4d3e-9b2a-6c1d2e3f4a5b"
  }
}

Every field

It takes no body.

Response · 200 OK, a sign-in from GoRunner’s own pages

dataobject

statusstring

pending — the popup has not bound yet; launched — the person is at the provider; connected — the tokens are stored; failed — see error; expired — the attempt aged out, or never existed.

One of pending, launched, connected, failed, expired.

connectionIdUUID

The connection signed in: for a sign-in that makes its connection, present once it connected.

reasonstring

Only when failed: denied — the person said no on the provider’s page; other_window — the sign-in finished in a browser that did not start it; service_error — the provider answered with an error; failed — anything on this side (the connection, its client, storage).

One of denied, other_window, service_error, failed, cancelled.

errorstring

Only when failed: why it ended, as a sentence for a person.

accountstring

Only when connected: who signed in, when the test after the sign-in named them.

previousAccountstring

Only when a sign-in again signed in as someone else than before: who it was.

accountChangedboolean

Response · 200 OK, a sign-in an API token started

dataobject

attemptIdstring

statusstring

pending — the provider has not sent the browser back yet; connected — the connection holds its tokens; failed — see reason.

One of pending, connected, failed.

connectionIdUUID

Only when connected: the connection made (or signed in again).

reasonstring

Only when failed: denied — the person said no on the provider’s page; service_error — the provider answered with an error; failed — anything on this side; cancelled — the sign-in was stopped (POST /api/connections/oauth2/attempts/{attemptId}/cancel, by the token that started it; no partner endpoint stops one); expired — the link ran out first.

One of denied, service_error, failed, cancelled, expired.