Skip to main content

Connectors and authentication

How connectors to outside systems authenticate — OAuth (browser-connected, not scriptable) versus credential-based — and the read/post surface a script gets.

The decision: your workflow needs to reach an outside system (Gmail, a calendar, a CRM). How does that connection get authorized, and what can a script do with it?

The two auth patterns​

  • OAuth connectors (Gmail, Google Calendar, Outlook, most social platforms). These are connected in the browser — a person clicks through the provider's consent screen once. A script cannot create an OAuth connection; it can only use one that already exists. Token refresh is owned by the connector's API client, not by your script — you never hand-refresh a token before calling.
  • Credential-based connectors (many ERP/CRM/API integrations). These authenticate with keys or credentials the user supplies. Depending on the connector, these can be configured without a browser round-trip.

Decision rules​

  1. Need an OAuth integration? Assume it is already connected. List the existing connections and use one — do not try to script the OAuth handshake. For Gmail, that's autessa.gmail.connectors.all to find a connection and autessa.gmail.connectors.get to inspect it.
  2. Don't re-check tokens. The connector's client refreshes tokens itself; your script just calls the read/post surface and trusts it to be authenticated.
  3. Respect the share/access model. A connector is shared with users and teams at an access level, exactly like other resources. Inspect it with the connector's getSharingDetails and adjust with share — e.g. autessa.gmail.connectors.getSharingDetails and autessa.gmail.connectors.share. See the sharing-permissions guide for what the access levels mean.
  4. Know the typical surface. Most connectors expose a small, consistent set: list/get the connection, update its settings, view and update which sub-resources are available (labels, calendars), and share it. Calendar connectors, for instance, add autessa.googleCalendar.connectors.syncCalendars and autessa.googleCalendar.connectors.viewAvailableCalendars.

Calendar tools and time zones​

When you build a calendar tool (the GOOGLE_CALENDAR_* and OUTLOOK_CALENDAR_* tool types), its config has a timeZone key. Leave timeZone empty to use the calendar's own default time zone — the connector's configured zone is applied automatically when you don't set one. Only set timeZone (to an IANA identifier like America/New_York) when the user explicitly asks for a specific zone. Do not invent or hard-code a time zone: guessing one silently shifts every event. Dates in these configs are yyyy-MM-dd and times are 24-hour HH:mm (kept as separate startDate/startTime and endDate/endTime keys, not one timestamp).

Worked examples​

A. Read mail from an existing Gmail connection. Find the connection with autessa.gmail.connectors.all, confirm which labels are available via autessa.gmail.connectors.viewAvailableLabels, then use it — no OAuth handshake in the script.

B. Schedule against a calendar. Use an already-connected calendar: list with autessa.googleCalendar.connectors.all, sync its calendars with autessa.googleCalendar.connectors.syncCalendars, and read events from it.

See also​

  • sharing-permissions — the access levels that govern who can use a connector.
  • automations — scheduled events and triggers that drive connector-backed tools.