Asking what is allowed

allowed() is a question you ask before you make the real call: "Is this connection ready, and what can I do with it?" It makes no call to Google or Microsoft. It only reads what the platform knows.

Use it to draw the right screen. A first-time visitor sees a Connect button. Someone who needs to sign in again sees a Reconnect button. Someone who is ready sees their data.

Call it

const s = await platform.connections.agenda.allowed()

if (s.status === 'active') {
  // connected: s.account is the account name, for example an email
} else {
  // anything else: show a button that goes to s.connect_url
}

reply = requests.get(f"{base}/__allowed", headers=headers, timeout=35)
s = reply.json()

if s["status"] == "active":
    ...
else:
    ...  # show a button that goes to s.get("connect_url")

allowed() takes no arguments and returns an Allowed object (the type is generated for you). Over HTTP it is GET on the connection's address plus /__allowed, with the binding token.

In user mode it needs the visitor's context like any other call. Outside a request it answers 401 caller_unknown, and it does the same for an anonymous visitor.

A connection that is not connected is not an error here. You get a normal answer with status: "not_connected", never a 403 or 409. The real calls would answer connection_required or no_grant.

The four states

Treat every state other than active as "this needs a connect button". The two states you will meet most are not_connected for a new visitor and needs_reauth for someone whose login lapsed.

What comes back

Each entry in permissions looks like this:

That is the three locks from the overview, shown one permission at a time. If effective is false for something you need, the person has to reconnect and allow it, or the owner has to give it.

A not-connected answer looks like this:

{
  "connection": "agenda",
  "provider": "google-workspace",
  "access": "user",
  "status": "not_connected",
  "permissions": [],
  "connect_url": "(the page to send them to)"
}

And a ready one:

{
  "connection": "agenda",
  "provider": "google-workspace",
  "access": "user",
  "status": "active",
  "account": "sam@example.com",
  "permissions": [
    { "name": "calendar.read", "label": "This lets your tool see your Google calendars and their events. It cannot change them.", "granted": true, "covered_by_scopes": true, "effective": true }
  ],
  "require_approval_for_writes": false,
  "connect_url": "(the page to send them to)"
}

About connect_url

connect_url is the one page where a visitor connects: one page, the provider's own consent screen, and the connection is made and given to your tool for that visitor. Use the value exactly as you got it. It is built by the platform, so do not assemble it yourself. The steps the visitor goes through are in connect, reconnect, switch and disconnect.

Use the same link for "Connect", "Connect again" and "Use a different account".

The link needs a signed-in Cohostly person. Send anonymous visitors to sign in first.

Using it in an app

The connect-accounts example calls allowed() for each provider and draws a card for each state. The steps are:

1. Not signed in as a person? Show a sign-in link.
2. Call allowed().
3. active: show the account name, then make the real call and show the data. Add a "Use a different account" link to connect_url.
4. needs_reauth: show a "Connect again" button to connect_url.
5. Anything else: show a "Connect" button to connect_url.
6. Also catch connection_required and connection_needs_reauth from the real call, in case the state changed in between.

Next: holding writes for approval.