This document describes the OAuth provider configuration system in Sim Studio. It covers the hierarchical provider structure, service definitions, scope management, and how providers integrate with tools and blocks. For information about the OAuth connection flow and credential creation, see OAuth Connection Flow For details on credential sets and webhook fan-out, see Credential Sets & Fan-out
The OAuth provider system defines a hierarchical configuration structure where base providers (like Google or Microsoft) contain multiple services (like Gmail, Google Drive, Outlook, Teams). Each service specifies its own OAuth scopes, icon, and metadata. This architecture allows users to connect a single base provider account (e.g., Google) but manage separate credentials for different services with different scope requirements.
The system supports 30+ OAuth providers organized into base providers with 50+ distinct services. Each service configuration includes:
Sources: apps/sim/lib/oauth/oauth.ts57-694 apps/sim/lib/oauth/types.ts3-145
Sources: apps/sim/lib/oauth/oauth.ts57-694
The OAUTH_PROVIDERS record in apps/sim/lib/oauth/oauth.ts57 defines the top-level structure. Each base provider has:
name - Display name (e.g., "Google", "Microsoft")icon - React component for the base provider iconservices - Record of service configurationsdefaultService - Key of the default service to show in UISources: apps/sim/lib/oauth/types.ts105-119
Each service configuration includes:
providerId - The OAuth provider identifier used by Better Auth (e.g., "google-email", "microsoft-teams")name and description - Display text for UIicon - Service-specific icon componentbaseProviderIcon - Reference to the base provider's iconscopes - Array of OAuth scopes required for this serviceEach service defines its required OAuth scopes. The system filters out basic identity scopes (userinfo.email, userinfo.profile) when displaying permissions to users in the OAuthRequiredModal.
| Service | Provider ID | Key Scopes |
|---|---|---|
| Gmail | google-email | gmail.send, gmail.modify, gmail.labels |
| Google Drive | google-drive | drive.file, drive |
| Google Calendar | google-calendar | calendar |
| Google Forms | google-forms | forms.body, forms.responses.readonly |
| Microsoft Teams | microsoft-teams | Chat.ReadWrite, ChannelMessage.Send, Team.ReadBasic.All |
| Outlook | outlook | Mail.ReadWrite, Mail.Send |
| OneDrive | onedrive | Files.Read, Files.ReadWrite |
| SharePoint | sharepoint | Sites.Read.All, Sites.ReadWrite.All |
Sources: apps/sim/lib/oauth/oauth.ts62-353
Sources: apps/sim/lib/oauth/oauth.ts62-75 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:64-85
When a tool requires OAuth credentials:
requiredProvider (service ID like "google-email")OAUTH_PROVIDERS[baseProvider].services[serviceId]scopes array from service configgetScopeDescription()The getScopeDescription() function maps technical OAuth scopes to user-friendly descriptions using the SCOPE_DESCRIPTIONS mapping.
Sources: apps/sim/lib/oauth/utils.ts13-143
The system distinguishes between:
services record (e.g., "gmail", "microsoft-teams")"google-email", "microsoft-teams")Sources: apps/sim/lib/oauth/oauth.ts62-75 apps/sim/lib/oauth/types.ts112-119 apps/sim/lib/auth/auth.ts14
The parseProvider() utility extracts the base provider from any provider ID. This allows the system to look up the base provider configuration and find the specific service metadata.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:22, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:48-49
Converts service IDs to provider IDs for initiating OAuth flows.
The system ensures that OAuth tokens are valid at the time of execution through automated refresh logic.
This server-side utility checks if an access token is expired and uses the associated refresh token to obtain a new one if necessary.
credentialId to an underlying account record apps/sim/app/api/auth/oauth/utils.ts33-58accessTokenExpiresAt with the current time apps/sim/app/api/auth/oauth/utils.ts133-136refreshOAuthToken and updates the account table with the new accessToken, expiresIn, and potentially a rotated refreshToken apps/sim/app/api/auth/oauth/utils.ts145-172Microsoft providers have unique requirements, such as extracting user info from ID tokens to avoid Graph API 403 errors apps/sim/lib/auth/auth.ts92-130 Additionally, the system tracks Microsoft refresh token expiry specifically using getMicrosoftRefreshTokenExpiry apps/sim/lib/auth/auth.ts84
Sources: apps/sim/app/api/auth/oauth/utils.ts110-196 apps/sim/lib/auth/auth.ts92-130
Tools in the registry reference OAuth providers via the requiredProvider field. This bridges the gap between the tool execution logic and the credential management system.
Sources: apps/sim/tools/registry.ts1-255 (referencing imports like airtableCreateRecordsTool, asanaCreateTaskTool, etc.)
Blocks reference OAuth providers in their configuration, which the UI uses to render the correct CredentialSelector and trigger the OAuthRequiredModal if no valid credential exists.
Sources: apps/sim/blocks/registry.ts1-127 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:37-46
Each provider and service has associated icon components. These are defined in the OAUTH_PROVIDERS configuration and imported from the central icons library.
Sources: apps/sim/lib/oauth/oauth.ts1-51 apps/sim/components/icons.tsx24-127
The system maintains a mapping from block types to icon components for consistent UI rendering across the application and documentation.
Sources: apps/docs/components/ui/icon-mapping.ts180-308
The Google base provider includes a wide array of specialized services:
| Service ID | Provider ID | Description |
|---|---|---|
gmail | google-email | Automate email workflows |
google-drive | google-drive | Streamline file organization |
google-sheets | google-sheets | Manage data with Sheets |
google-calendar | google-calendar | Schedule and manage events |
vertex-ai | vertex-ai | Full access to Vertex AI resources |
Sources: apps/sim/lib/oauth/oauth.ts62-238
The Microsoft base provider handles multiple enterprise services and includes special handling for refresh token expiry.
| Service ID | Provider ID | Description |
|---|---|---|
microsoft-teams | microsoft-teams | Manage Teams chats and channels |
outlook | outlook | Access Outlook mail |
onedrive | onedrive | Access personal/business files |
Sources: apps/sim/lib/oauth/oauth.ts240-353 apps/sim/lib/auth/auth.ts83-85
Some providers require custom authorization logic or instance-specific metadata:
getMicrosoftRefreshTokenExpiry to track when credentials need re-authentication apps/sim/lib/auth/auth.ts84The OAuthRequiredModal is the primary UI component for requesting permissions from users. It uses the OAUTH_PROVIDERS config to render:
client.oauth2.link apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:118-121.Refresh this wiki