Skip to main content

Connector Helper

The connector helper hands your script the live credentials behind a connected account — Gmail, HubSpot, QuickBooks, or any other connector your company has linked — so you can call the vendor's API directly with api.*. Token refresh is handled for you: if the access token is stale, the helper refreshes it before returning.

All methods are company-scoped: a script can only see connectors belonging to the company it runs in, and the helper requires the company context that tool execution provides. In contexts without it (such as computed columns), calls return a NO_COMPANY_CONTEXT error.

:::note Connector ids are sqid strings Pass the connector id as its sqid string — the connectorId returned by connector.listConnectors() (for example "MrG4pjkPqiic"). Raw numeric ids are deprecated: they still work for now but log a deprecation warning and will stop being accepted in a future release. :::

Methods​

  • Name
    connector.getAuth
    Type
    (connectorId: string) => string
    Description

    Everything needed for an authenticated call: access token, base URL (when the connector type has one), connector metadata, and any type-specific extra properties. Refreshes the token first if needed.

  • Name
    connector.getAccessToken
    Type
    (connectorId: string) => string
    Description

    Just the access token (or API key), refreshed if needed. Lighter envelope when you already know the endpoint.

  • Name
    connector.getMetadata
    Type
    (connectorId: string) => string
    Description

    The connector's type-specific metadata (account info, base URL, realm ids, and so on) without touching credentials.

  • Name
    connector.listConnectors
    Type
    () => string
    Description

    All active connectors for the current company — use this to discover connector ids from inside a script. The connectorId it returns is the sqid to pass back into the other methods.

Response shapes​

Every method returns a JSON string with success plus method-specific fields.

connector.getAuth(connectorId):

{
  "success": true,
  "connectorType": "GMAIL",
  "connectorName": "Support Inbox",
  "accessToken": "ya29.a0Af...",
  "baseUrl": "https://gmail.googleapis.com",
  "additionalProperties": { "...": "type-specific extras when present" },
  "metadata": { "...": "type-specific connector metadata when present" }
}

baseUrl, additionalProperties, and metadata are present only when the connector type provides them — check before using.

connector.getAccessToken(connectorId):

{ "success": true, "accessToken": "ya29.a0Af..." }

connector.getMetadata(connectorId):

{ "success": true, "connectorType": "QUICKBOOKS", "metadata": { "...": "..." } }

connector.listConnectors():

{
  "success": true,
  "connectors": [
    { "connectorId": "MrG4pjkPqiic", "connectorSqid": "MrG4pjkPqiic", "connectorName": "Support Inbox", "connectorType": "GMAIL", "isActive": true },
    { "connectorId": "9xTbQ2vWz0Ai", "connectorSqid": "9xTbQ2vWz0Ai", "connectorName": "Main CRM", "connectorType": "HUBSPOT", "isActive": true }
  ]
}

Error codes​

Failures return { "success": false, "errorCode": "...", "errorMessage": "..." }:

  • Name
    CONNECTOR_NOT_FOUND
    Type
    errorCode
    Description

    No connector with that id in this company. Call connector.listConnectors() to see what exists.

  • Name
    CONNECTOR_INACTIVE
    Type
    errorCode
    Description

    The connector is disabled — re-enable it in settings.

  • Name
    REFRESH_TOKEN_EXPIRED
    Type
    errorCode
    Description

    The refresh token was revoked upstream; the connector must be re-authenticated by a user.

  • Name
    TOKEN_REFRESH_FAILED
    Type
    errorCode
    Description

    The refresh attempt failed for another reason (transient upstream errors included).

  • Name
    NO_CREDENTIALS
    Type
    errorCode
    Description

    The connector exists but holds no usable access token for this type.

  • Name
    NO_COMPANY_CONTEXT
    Type
    errorCode
    Description

    The script isn't running with a company context (e.g. a computed column) — connector access requires tool execution.

  • Name
    SERVICE_NOT_INITIALIZED
    Type
    errorCode
    Description

    Connector services weren't available yet; retry later.

  • Name
    INTERNAL_ERROR
    Type
    errorCode
    Description

    Unexpected failure; errorMessage carries details.

Example: call the Gmail API with a connector token​

getAuth plus api.get is the whole pattern — the token goes straight into an Authorization header:

const auth = JSON.parse(connector.getAuth(12));   // your Gmail connector's id
if (!auth.success) {
  response.setResponse(JSON.stringify({ error: auth.errorCode + ": " + auth.errorMessage }));
} else {
  const res = JSON.parse(api.get(JSON.stringify({
    endpoint: "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread&maxResults=5",
    headers: { "Authorization": "Bearer " + auth.accessToken }
  })));

  if (res.statusCode !== 200) {
    response.setResponse(JSON.stringify({ error: "Gmail returned " + res.statusCode }));
  } else {
    const inbox = JSON.parse(res.body);
    console.log("unread messages:", inbox.resultSizeEstimate);
    response.setResponse(JSON.stringify({
      unread: inbox.resultSizeEstimate,
      messageIds: (inbox.messages || []).map(m => m.id)
    }));
  }
}

Prefer a dedicated connector tool type when one exists for your operation — it handles the vendor's API shape for you. The connector helper is for the gaps: endpoints no tool type covers yet, or vendor-specific parameters a config can't express.