Skip to content

External services — Overview

External services are the OAuth integrations that Forra can call on behalf of users: Google (Gmail, Drive, Calendar), Microsoft (Outlook, SharePoint, OneDrive), Slack, GitHub, Jira, Notion, Figma, etc.

Each service is:

  • Enabled at the tenant level (the admin chooses which ones are available);
  • Connected individually by each user (each user authorizes Forra to access their account);
  • Used by assistants and skills configured to connect to it.

Shared vs. custom OAuth clients

Forra provides shared OAuth clients for most common services. You do not need to create your own OAuth application — simply enable the service. Services currently provided include:

  • Google (Gmail, Drive, Calendar, Analytics, Play Developer)
  • Microsoft (Outlook, SharePoint, OneDrive, Teams)
  • Slack
  • GitHub
  • Atlassian (Jira)
  • Notion
  • Figma
  • HubSpot
  • Harvest
  • Mural
  • Airtable
  • Basecamp
  • Forra (API)

For any other service, or to use your own enterprise OAuth application, see Custom service.

Shared clients are pre-configured by the Forra team on request: the OAuth credentials (client_id, client_secret) remain managed by Forra and are not exposed in the tenant interface. On the tenant admin side, you only control the service's activation, visibility, and instructions.

Enabling a service

For services with a shared client, activation happens in two steps:

  1. Request pre-configuration from the Forra team, specifying the desired service(s). Forra enables the service with restricted visibility by default (admin only), to allow validation without exposing the service to end users before it is ready.
  2. Broaden visibility once configuration is validated: see Service visibility.

For a custom service, activation is done directly from the interface — you provide the OAuth credentials yourself.

Service visibility

Each service has a visibility control independent from its activation. This control determines who can connect their account to the service from Forra.

Options available on the service card:

  • Public — every tenant user can connect to the service.
  • Specific users — access limited to a list of accounts (by email).
  • Specific groups — access limited to members of the chosen groups. Groups come from the User Groups tab.

A newly added service is invisible until visibility has been set. Remember to set visibility to Public (or assign the desired groups/users) and save, otherwise no one will see the service.

Domain migration

If your Forra instance changes domain (e.g., moving from myclient.scout.mirego.com to scout.mirego.com), the Redirect URIs of the OAuth applications created at the providers (Google, Microsoft, etc.) must be updated. Contact the Forra team for the list of URIs to change.

Reference: JSON structure of a service

For reference, here is the shape of the JSON stored internally for a shared-client OAuth service. This representation is managed by the Forra team during pre-configuration; tenant administrators do not enter these values directly (except for a custom service).

{
  "name": "slack",
  "display_name": "Slack",
  "icon_url": "https://files.scout.mirego.com/external-services/slack-icon.png",
  "authorize_url": "https://slack.com/oauth/v2/authorize",
  "access_token_url": "https://slack.com/api/oauth.v2.access",
  "api_base_url": "https://slack.com/api/",
  "client_id": "...",
  "client_secret": "...",
  "client_kwargs": {"scope": ""},
  "authorize_url_params": {
    "user_scope": "channels:history channels:read chat:write users:read"
  },
  "additional_instructions": "Never post to #general unless explicitly asked to.",
  "api_documentation_url": "https://files.scout.mirego.com/external-services/slack.md"
}

The additional_instructions and api_documentation_url fields directly influence the behavior of assistants using this service.