Skip to content

Integration Credentials

Doable supports 530+ third-party integrations. For OAuth-based integrations to work, your instance needs access to OAuth Client ID and Client Secret credentials. This page explains the three ways credentials are resolved and how to configure them.

Credential Resolution Order

When a user clicks "Connect" on an integration, the API resolves OAuth credentials in this order:

flowchart TD
    A[User clicks Connect] --> B{DB: oauth_apps table?}
    B -- found --> Z[Use DB credentials]
    B -- not found --> C{Env: OAUTH_{ID}_CLIENT_ID?}
    C -- found --> Z
    C -- not found --> D{Shared env var?}
    D -- found --> Z
    D -- not found --> E[Error: No credentials]

  1. Database (oauth_apps table): Configured through the Admin panel (/admin, Integrations). Supports workspace-scoped or global (is_global = true) apps. Credentials are AES-256 encrypted at rest.

  2. Per-integration env vars: Pattern: OAUTH_{INTEGRATION_ID}_CLIENT_ID / OAUTH_{INTEGRATION_ID}_CLIENT_SECRET. The integration ID is uppercased with dashes replaced by underscores.

  3. Shared platform env vars: Google and GitHub services share a single OAuth app:

    • All Google services (YouTube, Gmail, Drive, Sheets, Calendar, etc.) use GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
    • All GitHub services use GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET

Tip

The admin UI at /admin, Integrations shows a blue ENV badge on integrations that are already configured via environment variables. These work without any manual setup in the admin panel.

Method 1: Environment Variables (Simplest)

Add credentials to your .env file. Best for self-hosted instances with a handful of integrations.

Google services (shared OAuth app)

All Google integrations (YouTube, Gmail, Drive, Sheets, Calendar, etc.) share a single OAuth app:

GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-secret
GOOGLE_REDIRECT_URI=http://localhost:4000/auth/google/callback

Optional: use a separate OAuth app for integrations vs login:

GOOGLE_INTEGRATIONS_CLIENT_ID=separate-client-id.apps.googleusercontent.com
GOOGLE_INTEGRATIONS_CLIENT_SECRET=separate-secret

Google Console Setup

In the Google Cloud Console:

  1. Go to APIs & Services, Credentials, OAuth 2.0 Client IDs
  2. Add the redirect URI: https://your-api-domain/integrations/oauth/callback
  3. Go to APIs & Services, OAuth consent screen, Scopes
  4. Add scopes for all Google APIs you want to use
  5. If the app is in "Testing" mode, add test user emails under "Test users"

GitHub services

GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-secret

Per-integration pattern

For any other OAuth integration, use the pattern:

OAUTH_SUPABASE_MGMT_CLIENT_ID=your-supabase-client-id
OAUTH_SUPABASE_MGMT_CLIENT_SECRET=your-supabase-secret

OAUTH_SLACK_CLIENT_ID=your-slack-client-id
OAUTH_SLACK_CLIENT_SECRET=your-slack-secret

OAUTH_LINEAR_CLIENT_ID=your-linear-client-id
OAUTH_LINEAR_CLIENT_SECRET=your-linear-secret

The env var name is derived from the integration ID: uppercase, dashes become underscores.

Integration ID Env Prefix
Supabase supabase-mgmt OAUTH_SUPABASE_MGMT_*
Slack slack OAUTH_SLACK_*
Linear linear OAUTH_LINEAR_*
Notion notion OAUTH_NOTION_*
Discord discord OAUTH_DISCORD_*

Redirect URI

All integration OAuth callbacks use a single redirect URI:

https://your-api-domain/integrations/oauth/callback

Override with INTEGRATIONS_OAUTH_REDIRECT_URI if your API is behind a reverse proxy with a different public URL.

Platform admins can configure credentials through the web UI without touching server env vars.

  1. Go to /admin, Integrations tab
  2. Find the integration, click the key icon
  3. Enter Client ID and Client Secret
  4. Click Save Credentials

Credentials are encrypted with ENCRYPTION_KEY using PostgreSQL pgp_sym_encrypt() (AES-256) and stored in the oauth_apps table. The secret is never exposed in any API response.

Global vs Workspace-scoped:

  • Platform admins (from /admin) create global OAuth apps: available to all workspaces
  • Workspace admins can create workspace-scoped OAuth apps: only usable within that workspace
  • Resolution priority: workspace-specific, then global, then env vars

Method 3: Both (Layered)

You can combine both methods. Env vars serve as the base layer, and admin-configured apps override them per-integration or per-workspace.

Controlling Visibility

By default, all 530+ integrations are shown to users. To restrict which integrations users see:

  1. Go to /admin, Integrations
  2. Enable only the integrations you want users to access
  3. Once at least one integration is explicitly enabled, the catalog filters to show only enabled ones

Note

Until you enable at least one integration, all are shown as a graceful fallback. This prevents breaking existing setups before an admin configures things.

Verifying Configuration

The admin panel shows visual indicators:

Badge Meaning
✅ Green check Enabled and credentials configured
🔵 ENV badge Credentials come from server environment variables
⚠️ Yellow warning Enabled but missing credentials; users will get errors

Use the "Env Vars" filter tab to see all integrations that are pre-configured via environment.

Security

  • OAuth client secrets are never returned in API responses
  • Database credentials use PostgreSQL pgp_sym_encrypt() with your ENCRYPTION_KEY
  • User OAuth tokens (after connection) are similarly encrypted in integration_connections
  • Admin endpoints require platform admin role verification
  • All operations are audit-logged with enabled_by user ID

See also