Integrations and OAuth

Register provider apps for the OAuth integrations your team uses. API-key blocks take member-supplied keys; service-account connections have their own configuration. Sim login providers are separate from integration connections, even when they share client credentials.

Prerequisites

• Serve Sim at a stable public origin and set NEXT_PUBLIC_APP_URL and BETTER_AUTH_URL to match.
• Have permission to register an app and grant the required provider permissions.
• Use the deployment's secret store or env files for client secrets.
• For webhook triggers, make Sim reachable from the provider's servers. Polling triggers instead require the scheduler.

Each OAuth connector has a provider ID. Its callback is:

https://<your-sim-domain>/api/auth/oauth2/callback/<provider-id>

Register the exact scheme, hostname, port, and path. Use no trailing slash. A provider that permits several callbacks can share one app across connectors or environments; GitHub Search's installation setup requires a separate app per deployment origin.

Set up an OAuth client

1. Set your public origin:

   NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
   BETTER_AUTH_URL=https://sim.yourdomain.com

2. Register the provider app and each connector callback you need. Configure provider-side APIs, permissions, consent, and distribution using the sections below.

3. Store the matching client ID/secret and restart the app. With Compose, recreate the app container after editing .env; a running process does not reread credentials.

4. Connect an account from the integration and confirm it returns to Sim with the account listed. Test an operation using that connection.

For Kubernetes, use the configured secret strategy: inline app.env becomes a chart-managed Secret; an existing Secret must contain the standard env keys; ESO requires externalSecrets.remoteRefs.app mappings and suppresses the inline Secret. Do not commit credentials to a values file. Explicit app.env credentials in existing-Secret mode are inlined into pod specs.

When changing an organization's saved OAuth provider configuration or scopes, an organization admin updates that configuration and affected members reconnect. Changing server variables alone does not replace an organization's saved provider settings.

Provider reference

Every provider ID below uses the callback format above unless its section specifies another flow. Integration references contain operation-specific requirements and their OAuth Scopes sections.

Google

Use one web OAuth client for the enabled Google services. The same client variables can also provide Sign in with Google; register /api/auth/callback/google separately if you use it.

1. Select your project in Google Cloud Console. Under APIs & Services → Library, enable the APIs for your services. Gmail, Drive, Calendar, and Meet use Gmail API, Google Drive API, Google Calendar API, and Google Meet REST API, respectively. For native Google Sheets reads through Drive, also enable the Google Sheets API; see Google's API enablement instructions.
2. Open Google Auth platform → Branding and enter the app name and contact details. Under Audience, choose Internal only for your Workspace organization; otherwise choose External and add test users while testing.
3. Configure Data Access → Add or remove scopes for external use. Sensitive/restricted scopes can require provider verification. Follow Google's consent guidance.
4. Open Google Auth platform → Clients → Create client, select Web application, and add each enabled connector's callback under Authorized redirect URIs. Add callbacks to an existing client if the deployment already uses one. See Google web credentials.
5. Store GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, restart Sim, and connect each service separately. Workspace administrators may need to approve the app.

For example, Gmail and Drive require both callbacks:

https://sim.yourdomain.com/api/auth/oauth2/callback/google-email
https://sim.yourdomain.com/api/auth/oauth2/callback/google-drive

Member-account scopes

These are the full Google member scope sets for the Search services below. Their connections also support workflow actions, so requested scopes can be broader than Search's read-only operations. The same Google identity does not imply the same grant for another service.

openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/gmail.labels

openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive

openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/calendar

openid
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
https://www.googleapis.com/auth/meetings.space.created
https://www.googleapis.com/auth/meetings.space.readonly

Other Google connectors declare their current scopes in their integration reference. Google Search service-account sources use separate domain-wide delegation scopes; those do not replace each member's OAuth connection. Configure delegation using the Gmail, Drive, and Calendar source guides. Meet member Search does not require a service account.

Microsoft

Use one Entra app registration for the enabled Microsoft connectors:

1. Create or select the app under Entra ID → App registrations. Choose the account types appropriate for the connectors you will use.
2. Under Authentication, register each connector callback as a Web redirect URI. If using Sim login, also register /api/auth/callback/microsoft.
3. Under API permissions → Add a permission, select the resource API and its Delegated permissions. Configure the scopes below; grant tenant admin consent when the permission requires it. These are member connections, not application/service-principal permissions. See Microsoft API permissions.
4. Create a client secret, store its value as MICROSOFT_CLIENT_SECRET, and store the application client ID as MICROSOFT_CLIENT_ID. Restart Sim and connect each service.

Every connector below requests openid, profile, email, and offline_access, plus its resource scopes:

For Power BI, use its Web callback and organizational account from the home tenant. The https://analysis.windows.net/powerbi/api/ prefix is part of the requested resource scopes. Power BI uses a separate connection from Microsoft Graph; Credential Groups and service-principal authentication are unsupported in this version. See Power BI.

For Dataverse/Dynamics 365, add Dynamics CRM → Delegated permissions → user_impersonation. The table shows the legacy Dynamics resource scope; environment-specific Dataverse connections request that environment's resource scope. Azure AD, Intune, Teams, and Planner permissions can require tenant-admin consent. Reconnect existing accounts after adding scopes.

Atlassian

Configure Confluence and Jira with their respective OAuth credentials and callbacks. A personal/member OAuth app is separate from an Atlassian service-account credential used to restrict a Search source.

1. In the Atlassian developer console, create or select an OAuth 2.0 integration.
2. Under Authorization → OAuth 2.0 (3LO), register the callback for the service using the exact Sim origin.
3. Under Permissions, add the corresponding Confluence/Jira API scopes below, including User Identity API → read:me. Sim requests offline_access for refresh tokens.
4. Enable sharing under Distribution so members other than the app owner can connect.
5. Store the service's client ID/secret from Settings, restart Sim, and connect from Integrations, selecting the intended site. After changing client/scopes, update the organization's provider configuration and reconnect affected accounts.

These are the full member connection scope sets. They include workflow writes; Search itself uses read operations. Jira's list includes Service Management and Assets permissions. Service-account read scopes from Search do not replace this app configuration. See Confluence OAuth and Jira OAuth.

read:confluence-content.all
read:confluence-space.summary
read:space:confluence
write:confluence-content
write:confluence-space
write:confluence-file
read:page:confluence
write:page:confluence
read:comment:confluence
write:comment:confluence
delete:comment:confluence
delete:attachment:confluence
delete:page:confluence
read:label:confluence
write:label:confluence
read:attachment:confluence
write:attachment:confluence
search:confluence
read:me
offline_access
read:hierarchical-content:confluence
read:content.metadata:confluence
read:user:confluence
read:confluence-user
read:group:confluence
read:task:confluence
write:task:confluence
write:space:confluence
delete:space:confluence
read:blogpost:confluence
write:blogpost:confluence
delete:blogpost:confluence
read:content.property:confluence
write:content.property:confluence
read:space.property:confluence
write:space.property:confluence
read:space.permission:confluence

read:jira-user
read:jira-work
write:jira-work
read:me
offline_access
read:issue.vote:jira
read:user:jira
delete:issue:jira
delete:comment:jira
delete:attachment:jira
delete:issue-worklog:jira
delete:issue-link:jira
read:servicedesk-request
write:servicedesk-request
manage:servicedesk-customer
read:servicedesk:jira-service-management
read:requesttype:jira-service-management
read:request:jira-service-management
write:request:jira-service-management
read:request.comment:jira-service-management
write:request.comment:jira-service-management
read:servicedesk.customer:jira-service-management
write:servicedesk.customer:jira-service-management
read:organization:jira-service-management
write:organization:jira-service-management
read:servicedesk.organization:jira-service-management
write:servicedesk.organization:jira-service-management
read:queue:jira-service-management
read:request.sla:jira-service-management
read:request.status:jira-service-management
write:request.status:jira-service-management
read:request.participant:jira-service-management
write:request.participant:jira-service-management
read:request.approval:jira-service-management
write:request.approval:jira-service-management
read:cmdb-object:jira
write:cmdb-object:jira
delete:cmdb-object:jira
read:cmdb-schema:jira
read:cmdb-type:jira
read:cmdb-attribute:jira

GitHub Search

Self-hosted GitHub Search uses a GitHub App for personal account connections and optional organization repository boundaries. Register your own App and configure the server variables below. Sim Cloud users use the GitHub Search setup flow directly.

1. 1

   Register the app

   For a team, open Your organizations → Settings for the organization that will own the App. For a personal App, open your account's Settings. Then choose Developer settings → GitHub Apps → New GitHub App.

   Give the App a unique, recognizable name, such as Your Company Sim Search, and set Homepage URL to your Sim URL.

   Under Identifying and authorizing users → Redirect URI (callback URL), enter:

   <NEXT_PUBLIC_APP_URL>/api/auth/oauth2/callback/github-repositories

   Replace <NEXT_PUBLIC_APP_URL> with your configured public origin, such as https://sim.example.com, without a trailing slash. The scheme, hostname, port, and path must match exactly; www and non-www hosts are different. See GitHub's callback matching rules.

   GitHub setting	Value for Sim Search
   Allow wildcard matching	Disabled
   Expire user authorization tokens	Enabled
   Request user authorization (OAuth) during installation	Disabled
   Enable Device Flow	Disabled
   Post installation → Setup URL	<NEXT_PUBLIC_APP_URL>/api/knowledge/github/setup/callback
   Post installation → Redirect on update	Enabled
   Webhook → Active	Disabled

   Authorization starts from Sim so the callback can finish the pending connection. The Setup URL returns installation approval to that same setup attempt. Keep Request user authorization (OAuth) during installation disabled: Sim starts account authorization when it is needed, before installation. See GitHub's Setup URL guide.

   Use a separate GitHub App per deployment origin so installation approval returns to the instance that started it. Before changing an existing App registration, deploy a Sim version that serves the setup callback; retain its user authorization callback.

   Live Search queries GitHub on demand and does not need a webhook. Ordinary GitHub knowledge-base connectors have their own polling/indexing path.

2. 2

   Set read permissions

   Expand Permissions → Repository permissions. Set Contents, Issues, and Pull requests to Read-only; leave mandatory Metadata at Read-only. Contents supports code reads; Issues and Pull requests allow the connected member’s App user token to search and read private issues and pull requests.

   Expand Account permissions and set Email addresses → Access: Read-only.

   Expand Organization permissions and set Members → Access: Read-only. Sim uses this to verify that the person connecting an organization installation is an organization owner. Existing installations must approve this permission update; repository read access alone cannot verify ownership.

   Permission area	Permission	Access
   Repository	Contents	Read-only
   Repository	Issues	Read-only
   Repository	Pull requests	Read-only
   Organization	Members	Read-only
   Repository	Metadata	Read-only
   Account	Email addresses	Read-only

   Leave other permissions at No access. Search does not need administration or write permissions. Existing installations must approve the additional issue and pull-request read permissions; members may need to reconnect. The service-side installation token remains narrowed to repository contents/metadata to verify source coverage; content search uses the member’s App user token. GitHub's registration guide explains these settings.

   GitHub App user tokens use these permissions rather than OAuth scopes. An empty scope value in the token response is expected; see GitHub's user token reference.

   Set Where can this GitHub App be installed? → Any account to support connections from accounts outside the App owner. This lets any GitHub account install and authorize the App, subject to that account's organization policies. Making the App public does not make repositories public or grant anyone Search access. See GitHub's App visibility rules.

   Select Create GitHub App.

3. 3

   Configure Sim

   On the App's General settings page, copy its numeric App ID and Client ID, select Generate a new client secret, and generate a Private key. The App slug is the final part of its public URL: https://github.com/apps/<app-slug>.

   Set all five variables using values from your GitHub App, then restart Sim:

   GITHUB_APP_ID=<numeric App ID>
   GITHUB_APP_SLUG=<app-slug>
   GITHUB_APP_CLIENT_ID=<Client ID>
   GITHUB_APP_CLIENT_SECRET=<Client secret>
   GITHUB_APP_PRIVATE_KEY=<complete RSA PEM private key>

   The private key must include its PEM header, footer, and contents. Sim accepts actual newlines or escaped \n sequences. When storing it in a JSON secret, use the plaintext JSON editor and encode each line break as \n inside the string. Single-line key/value fields can remove line breaks; replacing them with spaces makes the PEM invalid. Restart Sim after saving configuration changes.

   Keep the private key and client secret in the deployment's server configuration; organization admins select installations in Sim without entering these secrets.

   Configure all five variables on the app. If a separate worker indexes GitHub knowledge bases, configure its matching environment too; app secret changes do not update a separate worker. Live Search does not use an indexing worker.

   The Client ID is different from the numeric App ID. Use credentials from Developer settings → GitHub Apps. GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET belong to the separate GitHub sign-in integration and remain unchanged. Search does not read GITHUB_REPO_CLIENT_ID or GITHUB_REPO_CLIENT_SECRET.

   Keep Expire user authorization tokens enabled so Sim receives the refresh token it needs to renew personal connections.

   Complete the installation through the GitHub Search source setup.

   If you replace a deployment's GitHub App, an organization admin selects Settings → Credential Groups → Integrations → Update configurations. This applies the deployment's current App configuration to all existing providers while preserving their option IDs. Accounts whose App configuration changed must reconnect. Then reconnect personal GitHub accounts and connect an installation of the new App. Reconnecting alone cannot update the organization's saved App configuration.

If GitHub rejects redirect_uri, compare the App's registered callback with NEXT_PUBLIC_APP_URL followed by /api/auth/oauth2/callback/github-repositories. Keep wildcard matching disabled. If App installation setup is unavailable, confirm all five GITHUB_APP_* variables belong to the same App and include a complete RSA private key.

GitHub workflow blocks and knowledge-base token connections continue to use personal access tokens.

Other providers

For Help Scout, create an app under Your Profile > My Apps and set its redirection URL to https://<your-domain>/api/auth/oauth2/callback/helpscout. The App ID and App Secret are the client ID and secret. Help Scout has no OAuth scopes: a connection acts with the permissions of the user who authorizes it.

For Bitbucket, create an OAuth consumer and register https://<your-domain>/api/auth/oauth2/callback/bitbucket as its callback URL. Bitbucket fixes permissions on the consumer instead of narrowing them per authorization request. Enable exactly Account read, Repositories read/write, Pull requests read/write, Pipelines read/write, and Webhooks read/write (account, repository, repository:write, pullrequest, pullrequest:write, pipeline, pipeline:write, and webhook). The webhook permission is required for automatic trigger subscription management.

Some providers need more setup than a client ID, secret, and redirect URI:

Services with a different flow

Non-OAuth integration credentials

Many blocks authenticate with an API key the user pastes into the block, and need nothing from you.

Sim also has a "hosted key" mechanism, configured with the {PREFIX}_API_KEY_COUNT + {PREFIX}_API_KEY_1..N variables below, that lets the platform supply a key so users do not have to. The injection path is gated on the deployment being Sim's hosted platform (isHosted, derived from the app hostname), so on a self-hosted instance these variables do not remove the need for users to bring their own key. Treat these as hosted-platform configuration; they do not enable platform-supplied integration keys on a standard production self-hosted instance.

The variables, for reference:

Providers that take a _COUNT plus numbered keys distribute requests round-robin across them.

Triggers that need extra configuration

Webhook triggers receive callbacks from the provider and must be able to verify them:

When enabling the native Sim Slack trigger, configure all three variables together. Enable the extended-scope flags only after Slack approves the app for assistant:write, app_mentions:read, and im:history; otherwise Slack rejects OAuth authorization. Slack OAuth actions can use SLACK_CLIENT_ID and SLACK_CLIENT_SECRET without enabling the native trigger or supplying a signing secret.

Your deployment must also be reachable from the provider's servers for webhook triggers to fire — a Sim instance on a private network can use polling triggers but not webhook triggers. Polling triggers additionally require the scheduler; see Background Jobs.

Troubleshooting

Related docs

• Authentication
• Connected accounts
• Search
• Background jobs