Skip to main content

OAuth for Tools

Many of BasePeak.AI's built-in tools integrate with third-party services (GitHub, Google, Slack, and others) and require OAuth 2.0 to authenticate on behalf of users. Workspace administrators configure the OAuth application credentials so that users can connect these integrations without managing their own API credentials.

Where to configure​

OAuth app credentials are managed through the Tools page (/admin/tools). For any tool that requires OAuth, a configuration option is available directly on the tool's card. Tools that have not yet been configured display an indicator so you can identify which ones need attention.

Setting up an OAuth app​

Each tool provides step-by-step instructions for registering an OAuth application with the relevant service:

  1. Open the admin Tools page
  2. Locate the tool you want to configure
  3. Open its OAuth configuration
  4. Follow the embedded instructions to create an OAuth app in the third-party service's developer console
  5. Enter the Client ID and Client Secret (and any other required fields) from the registered app
  6. Save

Once saved, users can authenticate with that service through the tool without needing their own API credentials.

The redirect URI​

Every OAuth app you configure for tools from the admin interface has exactly one redirect URI — labelled Redirect URL in the dialog. It must be registered with the third-party service exactly as BasePeak.AI presents it:

https://<your-instance>/api/app-oauth/callback/<alias>

<alias> is an identifier made of lowercase letters, numbers and dashes, not the display name: for the provider presets it is google, slack, microsoft365, nextcloud-oidc and so on; for a custom app it is the alias you chose. The configuration dialog shows the full value with a copy button, at the step where the provider's console asks for it. Copy it from there rather than typing it out.

If your instance is reachable under more than one hostname, use the address configured for the instance (its canonical one). For the provider presets, the dialog builds the value from the address you are currently browsing the admin interface on, so on a secondary hostname it will show a URI the platform does not go on to send.

The bare instance URL (https://<your-instance>/) is not a valid redirect URI for a tool. Signing in to BasePeak.AI itself does accept a callback on the bare instance URL, which makes this an easy mistake — but tool OAuth requires the full path above. Some provider consoles ask for both a home page and a redirect URI; the bare instance URL belongs in the home page field only.

If the registered value and the full path don't match, the provider refuses the connection and shows an error instead of the consent screen — Google, for instance, reports Error 400: redirect_uri_mismatch. When that happens, compare the registered URI with the value in the configuration dialog.

Custom OAuth apps​

For tools that use a generic OAuth flow (rather than a named provider preset), you can register a custom OAuth app with your own client credentials. You choose the alias that completes the redirect URI described above, and the configuration dialog shows the finished URI for you to copy. The alias cannot be changed after the app is created, because it forms part of the registered redirect URI — so choose it deliberately.

Notes​

  • OAuth credentials are stored encrypted and are not exposed to users
  • Each tool's configuration dialog describes the exact scopes required for that integration
  • Admins can remove or reconfigure credentials at any time without affecting other tools