Skip to content

External service — Custom

Add an OAuth service that is not provided by Forra by default, or use your own OAuth application for an already supported service.

When to use this procedure

  • The desired service is not in the Forra shared clients list.
  • You want to use your own OAuth application for a supported service (scope control, compliance, branding).
  • You are integrating an internal API or a niche provider.

Prerequisites

  • An OAuth 2.0 (Authorization Code) application at the target provider.
  • The Client ID and Client Secret of that application.
  • The provider's OAuth URLs (authorize, token, api_base).
  • The list of required scopes.
  • The Redirect URI to declare on the provider side — see below.

1. Prepare the Redirect URI

The Redirect URI to use in the OAuth configuration at the provider takes the form:

https://{your-scout-domain}/api/external/callback/

If you are unsure which canonical domain to use, contact the Forra team.

2. Add the service in Forra

In Tenant Admin → External Services → OAuth Services section, click Add a service. Enter:

Identification

  • Service name (name): internal identifier (e.g., custom_crm).
  • Display name (display_name): name visible to users (e.g., Internal CRM).
  • Icon URL (icon_url): URL of a square image displayed in the interface.

OAuth endpoints

  • Authorize URL (authorize_url): e.g., https://your-service.com/oauth/authorize
  • Access token URL (access_token_url): e.g., https://your-service.com/oauth/token
  • API base URL (api_base_url): prefix used for API calls (e.g., https://api.your-service.com/v1/)
  • Authorize URL params (authorize_url_params): optional JSON for additional parameters (e.g., {"access_type": "offline", "prompt": "consent"})

Credentials

  • Client ID (client_id): OAuth Client ID provided by the service.
  • Client Secret (client_secret): OAuth Client Secret.

Scopes and instructions

  • Scopes (client_kwargs.scope): space-separated list of the permissions to request.
  • Organization usage (company_usage): short description of how your organization uses this service (e.g., "We use this CRM to manage our customer contacts in North America."). This information is injected into the assistants' context to help the LLM understand the usage context.
  • API documentation (api_documentation_url): URL of a Markdown file describing the API. This documentation is injected into the context of assistants using this service — it is what lets the LLM know how to phrase requests.

Visibility

Set who can connect their account to this service. See Overview — Visibility.

Save.

3. Test

Ask an authorized user to connect to the service from their Forra settings. Verify that they are redirected to the provider, then come back into Forra in a connected state.

Notes

  • The quality with which assistants use the service depends largely on the quality of the api_documentation_url file. Clear Markdown listing endpoints, parameters, and examples significantly improves results.
  • To host the API documentation file, the Forra team can publish it on files.scout.mirego.com if needed.