Skip to main content
Built-In Integrations is a separate OAuth microservice; this page covers the prerequisites and activation steps shared by all five supported integrations.
oauth.enabled is NOT required for WorkOS SSO, GitHub App, Entra ID, Okta, or Keycloak authentication. It only enables the Google/Microsoft/HubSpot/Notion/Salesforce tool integrations (Built-in Integrations). Enabling it unnecessarily adds a database pre-creation requirement and an extra running pod.

​
How It Works

The Built-In Integrations service (oauth) runs as a dedicated microservice alongside the main CrewAI application. It handles OAuth token exchange and stores encrypted access and refresh tokens in its own database. When a user connects a third-party tool (such as Gmail or HubSpot), their browser is redirected to the OAuth provider, which sends a callback to this service to complete the handshake. Because the service is separate, it must be explicitly enabled and requires its own ingress configuration so OAuth providers can reach the callback endpoints.

​
Prerequisites

​
1. Enable the OAuth Service

Add the following to your Helm values: 
oauth:
  enabled: true
  ingress:
    enabled: true
    className: nginx   # or your ingress class
    host: "crewai.your-company.com"  # can share host with main app
oauth.enabled: false is the default. Without setting this to true, no OAuth service resources are deployed and all Built-In Integrations are unavailable.
Setting oauth.enabled: true without routing causes OAuth provider callbacks to silently return 404. You must configure EITHER oauth.gateway (for GKE Gateway API) OR oauth.ingress (for NGINX/ALB). Neither is created by default. See the GCP Guide or AWS Guide for provider-specific routing examples.

​
2. Create the OAuth Database (External PostgreSQL only)

When using internal PostgreSQL (postgres.enabled: true), the OAuth database is created automatically. If postgres.enabled: false, you must create the database manually before running helm install or helm upgrade: 
CREATE DATABASE crewai_plus_oauth_production;
GRANT ALL PRIVILEGES ON DATABASE crewai_plus_oauth_production TO your_db_user;
Then reference that database name in your values: 
envVars:
  POSTGRES_OAUTH_DB: crewai_plus_oauth_production
The default value for POSTGRES_OAUTH_DB is oauth_db. The SQL above uses crewai_plus_oauth_production as an example; use whatever name you create. The name in your values file must match the database you create in PostgreSQL.

​
OAuth Redirect URI Patterns

When configuring your OAuth application in a third-party provider console, you will be asked for a redirect URI (also called a callback URL or authorized redirect URI). The correct URI depends on how you have configured the OAuth service ingress.
Ingress setupRedirect URI to register with the provider
NGINX with shared application hostnamehttps://<APPLICATION_HOST>/oauthsvc/oauth/add
Dedicated OAuth hostname (GKE Gateway, ALB)https://<OAUTH_HOST>/oauth/add
The path difference (/oauthsvc/oauth/add vs /oauth/add) reflects whether the OAuth service is accessed through a path-based proxy (NGINX) or a direct hostname. When oauth.ingress.path is set to "/" with a dedicated hostname, the /oauthsvc prefix is not present. See OAuth Ingress Configuration for the full ingress setup reference.

​
Activate Integrations After Deployment

After deploying with OAuth credentials configured, sync the integration definitions so the platform recognises them. This step is required for integrations to appear as available to users. Option 1: Via Admin Panel
  1. Log in to the CrewAI web UI as an admin
  2. Navigate to Admin Panel > Tools & Integrations
  3. Click Sync Integrations
Option 2: Via kubectl 
kubectl exec -it deploy/crewai-web -- bin/rails studio:tools:sync_crewai_tools
You must sync integrations after every helm upgrade that adds or changes OAuth credentials. Without syncing, newly configured integrations will not appear as available to users.

​
Adding an Integration to an Existing Deployment

To enable an additional integration after the initial install:
  1. Add the oauth.secrets.* values for the new integration to your values file.
  2. Apply the change with a Helm upgrade:
helm upgrade crewai-platform oci://registry.crewai.com/crewai/stable/crewai-platform \
  --values my-values.yaml
  1. Sync integrations using either method above.
No restart of existing pods is required beyond what Helm’s rolling update performs automatically.

​
Next Steps

Configure each specific integration: