Do END USERS need to authorize access to THEIR accounts?├── Yes → Use OAuth Connections│ (e.g., a user connects their Google Calendar)└── No → Use Managed Secrets (e.g., storing the Stripe API key)
Both use the same vault.request() method. The only difference is where the grant_id comes from: OAuth returns it when the user completes authorization; Managed Secrets returns it when you store a credential in the Developer Portal.
Users authorize access to their repos, issues, and PRs
Prefer for user-facing features
Managed Secret (PAT)
The backend needs server-level access to the org’s repos
Use for CI/CD, automation, org-wide access
Recommendation: OAuth for user-facing features. Use a managed secret (Personal Access Token) only when you need org-wide or service-level access that doesn’t belong to a specific user.
Users connect their Stripe accounts to the platform (marketplace model)
Use for multi-merchant platforms
Managed Secret (API key)
The backend processes payments using the organization’s Stripe account
Prefer for most apps
Recommendation: Managed Secret for most applications. Most apps process payments with a single Stripe account, not individual users’ accounts. Use OAuth (Stripe Connect) only for marketplaces or platforms where merchants connect their own Stripe accounts.
Users connect their Sentry accounts for cross-org error monitoring
Use for multi-tenant monitoring platforms
Managed Secret (auth token)
The backend monitors errors in the organization’s Sentry org
Prefer for most apps
Recommendation: Managed Secret for most applications. Most apps monitor a single Sentry organization. Use OAuth only if users need to connect their own Sentry orgs to the platform.
Users authorize the application to access their Discord identity, servers, or post on their behalf
Prefer for user-facing features
Managed Secret (bot token)
The bot operates server-wide using a bot token
Use for Discord bots and server automation
Recommendation: OAuth for user identity and user-scoped actions. Use a managed secret (bot token) for server-wide bot operations where no individual user context is needed.
Users connect their Airtable bases to the application
Prefer for user-facing features
Managed Secret (PAT)
The backend accesses the organization’s Airtable bases
Use for internal tools and automation
Recommendation: OAuth when users bring their own Airtable data. Use a managed secret (Personal Access Token) for internal dashboards or automation that accesses the organization’s bases.
Users connect their PagerDuty accounts for incident management
Use for multi-tenant incident platforms
Managed Secret (API key)
The backend manages incidents in the organization’s PagerDuty account
Prefer for most apps
Recommendation: Managed Secret for most applications. Most apps manage incidents in a single PagerDuty account. Use OAuth only if users need to connect their own PagerDuty accounts.
