Skip to main content
The CrewAI Built-in Integrations service provides secure authentication and token management for third-party integrations including Gmail, Google Calendar, Microsoft Outlook, and other services. It operates as a separate microservice with its own database for storing encrypted OAuth tokens.

​
Database Migration

When the Built-in Integrations service is enabled, the Helm chart automatically handles database schema initialization and migrations. Automatic Migration Behavior:
  • Installation: Database schema is created automatically during initial chart installation
  • Upgrades: Schema migrations run automatically before upgrading the Built-in Integrations service
  • Execution: Runs as a Kubernetes Job with a 5-minute timeout and up to 5 retry attempts
  • Database Readiness: When using internal PostgreSQL (postgres.enabled: true), the migration waits for PostgreSQL to become available before proceeding
Resource Requirements: The migration job uses modest resource allocations:
  • Memory: 128Mi requested, 256Mi limit
  • CPU: 100m requested, 300m limit
Troubleshooting Migration Failures: If the migration job fails, check the job logs: 
# List migration jobs
kubectl get jobs -n <namespace> | grep oauth-migrate

# View logs from the most recent migration
kubectl logs -n <namespace> job/<release-name>-oauth-migrate-<revision>
Common failure causes:
  • Database connectivity issues (check DB_HOST, DB_PORT, DB_PASSWORD)
  • Insufficient database permissions for the configured user
  • Database not created when using external PostgreSQL (manual creation required)
Database Creation:
  • Internal PostgreSQL: Database created automatically (configured via postgres.oauthDatabase)
  • External PostgreSQL: You must manually create the database specified in envVars.POSTGRES_OAUTH_DB (defaults to oauth_db)

​
Core Configuration

​
oauth.enabled
boolean
default:"false"
Enable or disable the Built-in Integrations service deployment.Purpose: Controls whether the Built-in Integrations service and its associated resources (Deployment, Service, Ingress) are deployed to the cluster.When Enabled:
  • Deploys Built-in Integrations service pods
  • Creates Built-in Integrations ClusterIP service
  • Optionally creates Ingress for external OAuth callbacks
  • Automatically configures Rails application with Built-in Integrations service URL
When Disabled:
  • No Built-in Integrations service resources deployed
  • Third-party integrations unavailable
  • OAuth-related secrets still created but unused
Example:
oauth:
  enabled: true
​
oauth.name
string
default:"oauth"
Component name for the Built-in Integrations service.Purpose: Used for resource naming and labeling. Generally should not be changed.
​
oauth.replicaCount
integer
default:"2"
Number of Built-in Integrations service pod replicas.High Availability: Multiple replicas ensure Built-in Integrations service availability during rolling updates and pod failures.Recommendations:
  • Development: 1
  • Production: 2 or more for high availability
  • High-traffic: 3-5 based on load
Example:
oauth:
  replicaCount: 3
​
oauth.port
integer
default:"8787"
Container port for the Built-in Integrations service.Default: 8787Note: This is the internal container port. External access is configured via Ingress.

​
Image Configuration

​
oauth.image.host
string
default:""
Container registry hostname for the Built-in Integrations service image.Default Behavior: If empty, falls back to global.imageRegistry.Example:
oauth:
  image:
    host: "images.crewai.com"
​
oauth.image.name
string
default:"proxy/crewai/crewai/crewai-oauth"
Built-in Integrations service image name.Default: "proxy/crewai/crewai/crewai-oauth"Note: The image name includes the full path to the Built-in Integrations service container image.
​
oauth.image.tag
string
default:"0.3.4"
Built-in Integrations service image tag.Production Recommendation: Use specific version tags for reproducible deployments.Example:
oauth:
  image:
    tag: "0.3.4"
​
oauth.image.pullPolicy
string
default:"IfNotPresent"
Image pull policy for Built-in Integrations service.Valid Values:
  • "IfNotPresent" - Pull only if not cached locally
  • "Always" - Always pull latest image
  • "Never" - Never pull, use cached only
Default: "IfNotPresent"
​
oauth.image.pullSecret
string
default:""
Kubernetes secret name for Built-in Integrations service image registry authentication.Default Behavior: If empty, falls back to image.pullSecret.Example:
oauth:
  image:
    pullSecret: "my-registry-secret"

​
Service Configuration

​
oauth.service.type
string
default:"ClusterIP"
Kubernetes service type for Built-in Integrations service.Default: "ClusterIP"Recommendation: Keep as ClusterIP and use Ingress for external access.Valid Values:
  • "ClusterIP" - Internal cluster access only (recommended)
  • "LoadBalancer" - External LoadBalancer (not recommended, use Ingress instead)
  • "NodePort" - Node port access (not recommended for production)
​
oauth.service.port
integer
default:"8787"
Service port for Built-in Integrations service.Default: 8787Note: This is the service port that other services use to communicate with the Built-in Integrations service internally.
​
oauth.service.targetPort
integer
default:"8787"
Target port on Built-in Integrations service pods.Default: 8787Note: Should match oauth.port.

​
Resource Limits

​
oauth.resources
object
CPU and memory resource requests and limits for Built-in Integrations service pods.Default Configuration:
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"
Tuning Guidelines:Low Traffic (< 100 users):
resources:
  limits:
    cpu: "500m"
    memory: "512Mi"
  requests:
    cpu: "250m"
    memory: "256Mi"
Medium Traffic (100-500 users):
resources:
  limits:
    cpu: "1"
    memory: "1Gi"
  requests:
    cpu: "500m"
    memory: "512Mi"
High Traffic (500+ users):
resources:
  limits:
    cpu: "2"
    memory: "2Gi"
  requests:
    cpu: "1"
    memory: "1Gi"

​
Health Probes

​
oauth.livenessProbe
object
Liveness probe configuration for Built-in Integrations service.Purpose: Kubernetes restarts the container if the liveness probe fails, recovering from deadlocks or hung processes.Default Configuration:
livenessProbe:
  initialDelaySeconds: 30
  periodSeconds: 30
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
Probe Details:
  • Endpoint: GET /health on port 8787
  • Initial Delay: 30 seconds (allows service startup time)
  • Check Interval: Every 30 seconds
  • Timeout: 5 seconds per check
  • Failure Threshold: 3 consecutive failures trigger restart
​
oauth.readinessProbe
object
Readiness probe configuration for Built-in Integrations service.Purpose: Kubernetes removes the pod from service load balancing if the readiness probe fails, preventing traffic to unhealthy pods.Default Configuration:
readinessProbe:
  initialDelaySeconds: 5
  periodSeconds: 10
  timeoutSeconds: 5
  successThreshold: 1
  failureThreshold: 3
Probe Details:
  • Endpoint: GET /health on port 8787
  • Initial Delay: 5 seconds
  • Check Interval: Every 10 seconds
  • Timeout: 5 seconds per check
  • Failure Threshold: 3 consecutive failures mark pod as not ready

​
Node Placement

​
oauth.nodeSelector
object
default:"{}"
Node selector labels for Built-in Integrations service pod placement.Default: {} (no node selector, schedule on any node)Use Cases:
  • Dedicated node pools for services
  • GPU or specialized hardware requirements
  • Cost optimization (spot/preemptible instances)
  • Compliance requirements (data locality)
Example:
oauth:
  nodeSelector:
    workload: services
    tier: backend

​
Ingress Configuration

The Built-in Integrations service requires external access for OAuth provider callbacks (redirects from Google, Microsoft, etc.). Ingress configuration provides secure HTTPS access to OAuth endpoints.
​
oauth.ingress.enabled
boolean
default:"false"
Enable Ingress for Built-in Integrations service external access.Default: falseRequired For: OAuth provider callbacks to work correctly.When Enabled:
  • Creates Ingress resource for OAuth endpoints
  • OAuth providers can send callbacks to your domain
  • Uses oauth.ingress.host or falls back to envVars.APPLICATION_HOST
When Disabled:
  • OAuth callbacks will fail
  • Third-party integrations cannot complete authentication flow
Important: OAuth callbacks require a publicly accessible HTTPS endpoint. If disabled, OAuth integrations will not function.
​
oauth.ingress.className
string
default:"nginx"
Ingress controller class name.Valid Values:
  • "nginx" - NGINX Ingress Controller
  • "alb" - AWS Application Load Balancer
Default: "nginx"
​
oauth.ingress.host
string
default:""
Hostname for Built-in Integrations service external access.Default Behavior: If empty, falls back to envVars.APPLICATION_HOST.Format: Fully qualified domain name (FQDN)Important:
  • Must be configured in DNS to point to your Ingress controller
  • Must match OAuth provider callback configuration
  • Requires valid TLS certificate for HTTPS
Example with Dedicated Subdomain:
oauth:
  ingress:
    enabled: true
    host: "oauth.crewai.company.com"
Example with Shared Domain (using fallback):
oauth:
  ingress:
    enabled: true
    host: ""  # Falls back to APPLICATION_HOST
Path Configuration:By default, the OAuth service is exposed at the /oauthsvc path prefix when sharing a hostname with the main application. When using NGINX Ingress Controller, the chart configures automatic path rewriting.For GKE or other ingress controllers that don’t support regex paths, use a separate hostname with path: "/". See path and pathType for details.
​
oauth.ingress.path
string
default:"/oauthsvc"
Path for the OAuth service ingress rule.Default: "/oauthsvc" (with regex pattern for NGINX)Purpose: Controls the URL path where the OAuth service is accessible. The default works with NGINX Ingress Controller which supports regex-based path rewriting.For GKE/ALB with Separate Hostname:When using GKE’s native ingress controller or AWS ALB with a dedicated OAuth hostname, set path: "/":
oauth:
  ingress:
    enabled: true
    className: gce
    host: "oauth.yourcompany.com"  # Separate hostname
    path: "/"
    pathType: "Prefix"
GKE’s native ingress controller does not support NGINX-style regex paths. Using a separate hostname with path: "/" is required for GKE compatibility.
​
oauth.ingress.pathType
string
default:"ImplementationSpecific"
Kubernetes Ingress pathType for the OAuth service.Default: "ImplementationSpecific" (for NGINX regex support)Valid Values:
  • "ImplementationSpecific" - Default for NGINX with regex paths
  • "Prefix" - Use with GKE/ALB when path: "/"
  • "Exact" - Exact path matching
Example for GKE:
oauth:
  ingress:
    path: "/"
    pathType: "Prefix"
​
oauth.ingress.annotations
object
default:"{}"
Additional annotations for the OAuth Ingress resource.Purpose: Advanced Ingress controller configuration not covered by built-in settings.Example:
oauth:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "letsencrypt-prod"
      nginx.ingress.kubernetes.io/rate-limit: "100"

​
AWS ALB Configuration

​
oauth.ingress.alb.scheme
string
default:"internet-facing"
AWS ALB scheme when using ALB Ingress controller.Valid Values:
  • "internet-facing" - Public internet access (required for OAuth)
  • "internal" - VPC-internal only
Default: "internet-facing"Note: OAuth callbacks require public internet access from OAuth providers.
​
oauth.ingress.alb.targetType
string
default:"ip"
AWS ALB target type.Valid Values:
  • "ip" - Target pods by IP (recommended for most cases)
  • "instance" - Target EC2 instances via NodePort
Default: "ip"
​
oauth.ingress.alb.certificateArn
string
default:""
AWS ACM certificate ARN for HTTPS.Required: Yes (for ALB with HTTPS)Format: arn:aws:acm:region:account:certificate/idExample:
oauth:
  ingress:
    className: alb
    alb:
      certificateArn: "arn:aws:acm:us-west-2:123456789012:certificate/abc-def-123"
​
oauth.ingress.alb.sslPolicy
string
default:"ELBSecurityPolicy-TLS-1-2-2017-01"
AWS ALB SSL policy.Default: "ELBSecurityPolicy-TLS-1-2-2017-01"Other Options:
  • "ELBSecurityPolicy-TLS13-1-2-2021-06" - TLS 1.3 and 1.2
  • "ELBSecurityPolicy-FS-1-2-2019-08" - Forward secrecy
Recommendation: Use TLS 1.2 minimum for security.

​
NGINX Ingress Configuration

​
oauth.ingress.nginx.sslRedirect
boolean
default:"true"
Redirect HTTP to HTTPS automatically.Default: trueRecommendation: Keep enabled for security. OAuth requires HTTPS.
​
oauth.ingress.nginx.proxyBodySize
string
default:"10m"
Maximum request body size.Default: "10m" (10 megabytes)Purpose: Limits size of OAuth requests and responses.
​
oauth.ingress.nginx.enableCors
boolean
default:"true"
Enable CORS (Cross-Origin Resource Sharing).Default: truePurpose: Allows Built-in Integrations service to be called from web application hosted on different subdomain.
​
oauth.ingress.nginx.corsAllowMethods
string
default:"GET, POST, OPTIONS"
Allowed HTTP methods for CORS requests.Default: "GET, POST, OPTIONS"Note: OAuth flows primarily use GET and POST methods.
​
oauth.ingress.nginx.corsAllowHeaders
string
Allowed HTTP headers for CORS requests.Default: Standard headers for OAuth and API requests.
​
oauth.ingress.nginx.corsAllowOrigin
string
default:"*"
Allowed origins for CORS requests.Default: "*" (allow all origins)Security Note: For production, consider restricting to specific domains:
oauth:
  ingress:
    nginx:
      corsAllowOrigin: "https://crewai.company.com"
​
oauth.ingress.nginx.corsAllowCredentials
boolean
default:"true"
Allow credentials (cookies, authorization headers) in CORS requests.Default: truePurpose: Required for OAuth cookie-based authentication.
​
oauth.ingress.nginx.tls.enabled
boolean
default:"false"
Enable TLS termination at NGINX.Default: falseWhen Enabled: Requires TLS certificate in Kubernetes secret specified by oauth.ingress.nginx.tls.secretName.Example:
oauth:
  ingress:
    nginx:
      tls:
        enabled: true
        secretName: "oauth-tls-cert"
​
oauth.ingress.nginx.tls.secretName
string
default:""
Kubernetes secret name containing TLS certificate and key.Required When: oauth.ingress.nginx.tls.enabled: trueSecret Format:
apiVersion: v1
kind: Secret
metadata:
  name: oauth-tls-cert
type: kubernetes.io/tls
data:
  tls.crt: <base64-encoded-certificate>
  tls.key: <base64-encoded-private-key>

​
Gateway API Configuration

Gateway API HTTPRoute configuration for OAuth service (alternative to Ingress).
Gateway API vs Ingress: Gateway API is the modern successor to Ingress and is recommended for new deployments, especially on GKE. It provides standardized routing and better multi-tenancy support.
​
oauth.gateway.enabled
boolean
default:"false"
Enable Gateway API HTTPRoute for OAuth service.When Enabled:
  • Creates an HTTPRoute resource for OAuth service
  • Requires gateway.enabled: true at the global level
  • Routes traffic from Gateway listeners to OAuth service
  • Automatically configures health check path to /health
When Disabled:
  • No HTTPRoute created for OAuth service
  • Use oauth.ingress.* instead
Example - Shared Hostname with Path Prefix:
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed

oauth:
  enabled: true
  gateway:
    enabled: true
    pathPrefix: /oauthsvc  # OAuth at https://crewai.company.com/oauthsvc
Example - Dedicated OAuth Hostname:
gateway:
  enabled: true
  gatewayClassName: gke-l7-global-external-managed

oauth:
  enabled: true
  gateway:
    enabled: true
    hostname: oauth.company.com
    pathPrefix: /  # OAuth at https://oauth.company.com/
Prerequisites:
  • Gateway API CRDs installed in cluster
  • Gateway resource exists (created via gateway.create: true or externally)
  • On GKE: Run gcloud container clusters update CLUSTER --gateway-api=standard
On GKE, the chart automatically creates a HealthCheckPolicy that configures the load balancer’s health probes to use /health as the check path. This prevents health check failures caused by Rails’ HostAuthorization middleware.
​
oauth.gateway.hostname
string
default:""
Dedicated hostname for OAuth service (optional).Default Behavior: When empty, defaults to envVars.APPLICATION_HOST (shared hostname with web service).Purpose: Use a separate hostname for OAuth callbacks instead of sharing the web application’s hostname.When to Use Dedicated Hostname:
  • GKE or other ingress controllers that don’t support path rewriting
  • Organizational preference for separate OAuth domain
  • Security requirement for isolated OAuth traffic
Example - Shared Hostname (Default):
envVars:
  APPLICATION_HOST: crewai.company.com

oauth:
  gateway:
    enabled: true
    hostname: ""  # Uses crewai.company.com
    pathPrefix: /oauthsvc  # OAuth at /oauthsvc path
Example - Dedicated Hostname:
oauth:
  gateway:
    enabled: true
    hostname: oauth.company.com
    pathPrefix: /  # OAuth at root path
When using a dedicated hostname:
  1. Add the hostname to your Gateway’s TLS certificate or certificate map
  2. Configure DNS to point to the same Gateway IP address
  3. Update OAuth provider callback URLs to use the dedicated hostname
​
oauth.gateway.pathPrefix
string
default:"/oauthsvc"
Path prefix for OAuth service routes.Default: "/oauthsvc" (shared hostname mode)Purpose: Defines the URL path where OAuth endpoints are accessible.Values:
  • "/oauthsvc" - Share hostname with web service (e.g., https://crewai.company.com/oauthsvc)
  • "/" - Use dedicated hostname (e.g., https://oauth.company.com/)
Path Rewriting: When pathPrefix is not "/", the chart automatically configures URLRewrite to strip the prefix when forwarding to the OAuth service.Example - Shared Hostname:
oauth:
  gateway:
    enabled: true
    pathPrefix: /oauthsvc

# OAuth callback URLs:
# https://crewai.company.com/oauthsvc/v1/auth/google/callback
# https://crewai.company.com/oauthsvc/v1/auth/microsoft/callback
Example - Dedicated Hostname:
oauth:
  gateway:
    enabled: true
    hostname: oauth.company.com
    pathPrefix: /

# OAuth callback URLs:
# https://oauth.company.com/v1/auth/google/callback
# https://oauth.company.com/v1/auth/microsoft/callback
The Gateway API HTTPRoute automatically configures path rewriting when using a non-root pathPrefix, eliminating the need for manual rewrite configuration.
Complete Example - Shared Hostname: 
# Global Gateway configuration
gateway:
  enabled: true
  create: true
  gatewayClassName: gke-l7-global-external-managed
  annotations:
    networking.gke.io/certmap: crewai-cert-map
  listeners:
    - name: https
      protocol: HTTPS
      port: 443

# Web service
web:
  gateway:
    enabled: true
    hostnames:
      - crewai.company.com

# OAuth service - shared hostname with path prefix
oauth:
  enabled: true
  gateway:
    enabled: true
    pathPrefix: /oauthsvc
Complete Example - Dedicated Hostname: 
# Global Gateway configuration
gateway:
  enabled: true
  create: true
  gatewayClassName: gke-l7-global-external-managed
  annotations:
    networking.gke.io/certmap: crewai-cert-map
  listeners:
    - name: https
      protocol: HTTPS
      port: 443

# Web service
web:
  gateway:
    enabled: true
    hostnames:
      - crewai.company.com

# OAuth service - dedicated hostname
oauth:
  enabled: true
  gateway:
    enabled: true
    hostname: oauth.company.com
    pathPrefix: /
See Also: Gateway API Configuration for Gateway resource configuration.

​
Environment Configuration

​
oauth.config.logLevel
string
default:"info"
Built-in Integrations service log level.Valid Values: "debug", "info", "warn", "error"Default: "info"Recommendations:
  • Production: "info" or "warn"
  • Development: "debug"
Example:
oauth:
  config:
    logLevel: "debug"
​
oauth.config.googleWorkspaceDomain
string
default:""
Support Google Workspace identity by restricting Google apps to a specific domain.Purpose: When set, only users with email addresses from the specified Google Workspace domain can authenticate via Google Built-In integrations.Format: Domain name (e.g., company.com)Example:
oauth:
  config:
    googleWorkspaceDomain: "company.com"
This setting only applies to Google Workspace integrations (Gmail, Calendar, Drive, etc.). See Google Workspace Integrations - Support Google Workspace Identity for more details.

​
OAuth Secrets Configuration

OAuth secrets are configured via the oauth.secrets values and are used to secure the Built-in Integrations service and enable third-party integrations. These secrets are separate from the main application secrets and are stored in a dedicated Kubernetes secret resource.

​
Auto-Generated Secrets

​
oauth.secrets.cookieSecret
string
default:""
Secret key for signing OAuth session cookies.Auto-Generation: If not provided, automatically generated as a 64-character random alphanumeric string and persisted across upgrades.Purpose: Secures OAuth flow session data during the authentication process.Manual Generation:
openssl rand -base64 64
Leave Empty: To use auto-generated value (recommended).
​
oauth.secrets.dbEncryptionKey
string
default:""
Encryption key for OAuth tokens stored in the database.Auto-Generation: If not provided, automatically generated as a 64-character hexadecimal string and persisted across upgrades.Purpose: Encrypts sensitive OAuth tokens (access tokens, refresh tokens) at rest in the OAuth database.Format: 64-character hexadecimal string.Manual Generation:
openssl rand -hex 32
Leave Empty: To use auto-generated value (recommended).
​
oauth.secrets.internalApiKey
string
default:""
Internal API key for authentication between the Built-in Integrations service and Rails application.Auto-Generation: If not provided, automatically generated as a 64-character random alphanumeric string and persisted across upgrades.Purpose: Enables secure service-to-service communication for OAuth operations.Important: This value is automatically duplicated as CREWAI_OAUTH_API_KEY in the main application secrets for Rails to use.Manual Generation:
openssl rand -base64 64 | tr -d '\n'
Leave Empty: To use auto-generated value (recommended).

​
OAuth Provider Credentials

OAuth provider credentials are optional and only required if you want to enable specific OAuth integrations. Each provider supports both provider-level credentials (shared across all products) and product-specific overrides.

​
Google OAuth Provider

​
oauth.secrets.google.clientId
string
default:""
Google OAuth client ID used as default for all Google products.Purpose: Shared Google OAuth client ID. If product-specific client IDs are not provided, this value is used for all Google integrations (Gmail, Calendar, Drive, etc.).Obtain From: Google Cloud Console → APIs & Services → CredentialsExample:
oauth:
  secrets:
    google:
      clientId: "123456789-abcdefg.apps.googleusercontent.com"
      clientSecret: "GOCSPX-abc123..."
​
oauth.secrets.google.clientSecret
string
default:""
Google OAuth client secret used as default for all Google products.Purpose: Shared Google OAuth client secret for all Google integrations.
​
oauth.secrets.google.drivePickerKey
string
default:""
Google Drive Picker API key for file picker functionality.Purpose: Enables Google Drive file picker UI in the application for selecting files from Google Drive.Obtain From: Google Cloud Console → APIs & Services → Credentials → Create Credentials → API KeyImportant: This is an API key (not OAuth credentials) specifically for the Google Picker API.Example:
oauth:
  secrets:
    google:
      clientId: "123456789-abcdefg.apps.googleusercontent.com"
      clientSecret: "GOCSPX-abc123..."
      drivePickerKey: "AIzaSyAbc123def456..."
Product-Specific Google OAuth Overrides: You can override the provider-level credentials for specific Google products. If not provided, the provider-level credentials are used.
​
oauth.secrets.google.calendar.clientId
string
default:""
Google Calendar-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.calendar.clientSecret
string
default:""
Google Calendar-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.gmail.clientId
string
default:""
Gmail-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.gmail.clientSecret
string
default:""
Gmail-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.

​
Gmail Triggers Configuration

Gmail Triggers enable real-time email notifications using Google Cloud Pub/Sub. This requires a separate service account (not OAuth credentials) for Pub/Sub management.
​
oauth.secrets.google.gmail.triggers.serviceAccountCredentials
object
default:"{}"
Google Cloud service account credentials for Gmail push notification triggers.Purpose: Authenticates with Google Cloud to manage Pub/Sub topics and subscriptions for Gmail push notifications.Required APIs: Gmail API, Cloud Pub/Sub API, Cloud Resource Manager APIRequired Role: roles/pubsub.admin on the Google Cloud projectObtain From: Google Cloud Console → IAM & Admin → Service Accounts → Create Service Account → Create Key (JSON)Example:
oauth:
  secrets:
    google:
      gmail:
        triggers:
          serviceAccountCredentials:
            type: service_account
            project_id: your-project
            private_key_id: abc123...
            private_key: |
              -----BEGIN PRIVATE KEY-----
              MIIEvgIBADANBgkqhkiG9w0BAQEFAASC...
              -----END PRIVATE KEY-----
            client_email: gmail-triggers@your-project.iam.gserviceaccount.com
            client_id: "123456789"
            auth_uri: https://accounts.google.com/o/oauth2/auth
            token_uri: https://oauth2.googleapis.com/token
            auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
            client_x509_cert_url: https://www.googleapis.com/robot/v1/metadata/x509/...
            universe_domain: googleapis.com
​
oauth.secrets.google.drive.clientId
string
default:""
Google Drive-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.drive.clientSecret
string
default:""
Google Drive-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.contacts.clientId
string
default:""
Google Contacts-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.contacts.clientSecret
string
default:""
Google Contacts-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.sheets.clientId
string
default:""
Google Sheets-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.sheets.clientSecret
string
default:""
Google Sheets-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.slides.clientId
string
default:""
Google Slides-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.slides.clientSecret
string
default:""
Google Slides-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.
​
oauth.secrets.google.docs.clientId
string
default:""
Google Docs-specific OAuth client ID.Override: Falls back to oauth.secrets.google.clientId if not provided.
​
oauth.secrets.google.docs.clientSecret
string
default:""
Google Docs-specific OAuth client secret.Override: Falls back to oauth.secrets.google.clientSecret if not provided.

​
Microsoft OAuth Provider

​
oauth.secrets.microsoft.clientId
string
default:""
Microsoft OAuth client ID used as default for all Microsoft products.Purpose: Shared Microsoft OAuth client ID. If product-specific client IDs are not provided, this value is used for all Microsoft integrations (Outlook, OneDrive, Teams, etc.).Obtain From: Microsoft Azure Portal → App registrationsExample:
oauth:
  secrets:
    microsoft:
      clientId: "12345678-1234-1234-1234-123456789abc"
      clientSecret: "abc123~def456..."
​
oauth.secrets.microsoft.clientSecret
string
default:""
Microsoft OAuth client secret used as default for all Microsoft products.Purpose: Shared Microsoft OAuth client secret for all Microsoft integrations.
​
oauth.secrets.microsoft.tenantId
string
default:""
Microsoft Azure AD tenant ID for single-tenant authentication.Purpose: When set, restricts authentication to users from the specified Azure AD tenant only (single-tenant mode). If not set, uses Microsoft’s common endpoint allowing users from any Azure AD organization (multi-tenant mode).Obtain From: Microsoft Azure Portal → Microsoft Entra ID → Overview → Directory (tenant) IDExample:
oauth:
  secrets:
    microsoft:
      clientId: "12345678-1234-1234-1234-123456789abc"
      clientSecret: "abc123~def456..."
      tenantId: "87654321-4321-4321-4321-cba987654321"
Product-Specific Microsoft OAuth Overrides:
​
oauth.secrets.microsoft.outlook.clientId
string
default:""
Outlook-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.outlook.clientSecret
string
default:""
Outlook-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.outlook.tenantId
string
default:""
Outlook-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.
​
oauth.secrets.microsoft.onedrive.clientId
string
default:""
OneDrive-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.onedrive.clientSecret
string
default:""
OneDrive-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.onedrive.tenantId
string
default:""
OneDrive-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.
​
oauth.secrets.microsoft.teams.clientId
string
default:""
Teams-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.teams.clientSecret
string
default:""
Teams-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.teams.tenantId
string
default:""
Teams-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.
​
oauth.secrets.microsoft.sharepoint.clientId
string
default:""
SharePoint-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.sharepoint.clientSecret
string
default:""
SharePoint-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.sharepoint.tenantId
string
default:""
SharePoint-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.
​
oauth.secrets.microsoft.excel.clientId
string
default:""
Excel-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.excel.clientSecret
string
default:""
Excel-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.excel.tenantId
string
default:""
Excel-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.
​
oauth.secrets.microsoft.word.clientId
string
default:""
Word-specific OAuth client ID.Override: Falls back to oauth.secrets.microsoft.clientId if not provided.
​
oauth.secrets.microsoft.word.clientSecret
string
default:""
Word-specific OAuth client secret.Override: Falls back to oauth.secrets.microsoft.clientSecret if not provided.
​
oauth.secrets.microsoft.word.tenantId
string
default:""
Word-specific Azure AD tenant ID.Override: Falls back to oauth.secrets.microsoft.tenantId if not provided.

​
Other OAuth Providers

​
oauth.secrets.hubspot.clientId
string
default:""
HubSpot OAuth client ID.Obtain From: HubSpot Developer PortalExample:
oauth:
  secrets:
    hubspot:
      clientId: "12345678-abcd-1234-abcd-123456789abc"
      clientSecret: "abc123def456..."
​
oauth.secrets.hubspot.clientSecret
string
default:""
HubSpot OAuth client secret.
​
oauth.secrets.notion.clientId
string
default:""
Notion OAuth client ID.Obtain From: Notion IntegrationsExample:
oauth:
  secrets:
    notion:
      clientId: "secret_abc123def456..."
      clientSecret: "secret_xyz789..."
​
oauth.secrets.notion.clientSecret
string
default:""
Notion OAuth client secret.
​
oauth.secrets.salesforce.clientId
string
default:""
Salesforce OAuth consumer key (client ID) from an External Client App.Obtain From: Salesforce Setup → External Client App ManagerExample:
oauth:
  secrets:
    salesforce:
      clientId: "3MVG9..."
      clientSecret: "ABCDEF123456..."
​
oauth.secrets.salesforce.clientSecret
string
default:""
Salesforce OAuth consumer secret (client secret).
OAuth Secrets: See Secrets Reference - Built-in Integrations Secrets for Built-in Integrations service secrets configuration including:
  • OAUTH_COOKIE_SECRET - Session cookie signing
  • OAUTH_DB_ENCRYPTION_KEY - Token encryption
  • OAUTH_INTERNAL_API_KEY - Service-to-service authentication
  • OAuth provider credentials (Google, Microsoft, HubSpot, Notion, Salesforce)
OAuth Database: The Built-in Integrations service uses a separate database (oauth_db). When using the internal PostgreSQL instance (postgres.enabled: true), the database is created automatically. When using an external database (postgres.enabled: false), you must manually create the database specified in envVars.POSTGRES_OAUTH_DB (defaults to oauth_db). See PostgreSQL Configuration and Environment Variables - POSTGRES_OAUTH_DB for configuration details. Automatic URL Configuration: When Built-in Integrations service is enabled, the Rails application is automatically configured with CREWAI_OAUTH_API_BASE_URL pointing to the internal Built-in Integrations service URL. See Environment Variables - Built-in Integrations for details.