| name | vellum-oauth-integrations |
| description | Act on behalf of your user in any third-party software that supports OAuth 2.0 |
| compatibility | Designed for Vellum personal assistants |
| metadata | {"emoji":"🔌","vellum":{"category":"integrations","display-name":"Vellum OAuth Integrations"}} |
Using OAuth Integrations
Integrating with a third-party software via OAuth is typically used to perform actions on behalf of the user. It involves having the user log in using their own credentials, specifying the scopes that they want to provide, and then afterwards, API requests can be made on their behalf.
Important: Avoid reaching for an OAuth integration if your intent is to act as yourself rather than as your user.
The Assistant OAuth CLI
You are provided with the assistant oauth CLI for performing all necessary oauth-related actions.
Important: When in doubt how a command works or how to do something, read the references at the bottom. Never guess at how the CLI works. Read references and use the --help flag for any command you're about to run.
Viewing Available OAuth Providers
Vellum assistants can natively integrate with any application that supports OAuth 2.0. Many OAuth providers come pre-configured and ready to use. You can view them by running:
assistant oauth providers list
You can also search for specific providers. Here's an example that searches for the "google" provider:
assistant oauth providers list --provider-key google
Managed vs Your-Own Mode
All providers support "your-own" mode and some support "managed" mode.
Default: Managed Mode
"managed" mode relies on a first-class integration with the Vellum Platform. Managed mode is typically easier to set up and get going, often only requiring the user to log in with no additional configuration needed before they can begin using the integration. Managed mode is the recommended method for most users, especially those that are less technical or newer to their Vellum assistant.
When a task needs a managed OAuth connection, present it in chat with ui_show using surface_type: "oauth_connect" instead of sending the user to Settings or trying to open the OAuth flow from shell. See Connecting Accounts for the exact surface shape.
Note that using managed mode:
- Requires an account with the Vellum Platform
- May result in billable usage
- Requires that requests to the third party are sent through Vellum's servers
Your-Own Mode
"your-own" mode requires that the user creates their own OAuth application directly with the third-party and then enter the application's Client ID and Client Secret into Vellum.
Your-own mode is typically best if:
- Vellum does not have a first-party integration with the provider and managed mode is not supported
- The user is more tech-savvy and comfortable setting up OAuth apps
- The user does not want to create an account with the Vellum Platform
- The user is more sensitive to potential billing implications
- The user is sensitive to their data going to the Vellum Platform
How to Choose
Default to managed mode whenever the provider supports it. Check support with:
assistant oauth providers get <provider-key> --json | jq -r '.managedServiceConfigKey'
If this returns a non-null value, managed mode is supported and should be your starting recommendation. Only fall back to your-own mode if:
- The provider does not support managed mode (
managedServiceConfigKey is null), OR
- The user explicitly wants their own OAuth app (e.g. they're running self-hosted, they're privacy-sensitive, they're configuring a per-assistant Slack app), OR
- The user already has a working your-own connection — don't re-recommend managed mid-flow for already-connected providers.
Do not present managed and your-own as equivalent choices to a fresh user. Lead with managed, then offer your-own as an alternative if they push back.
Differentiating & Setting a Provider's Mode
You can determine whether a given provider supports managed mode based on the details returned by:
assistant oauth providers list
assistant oauth providers get <provider-key>
You can determine what mode the provider is currently set to use with:
assistant oauth mode <provider-key>
You can update which mode a given provider should use with:
assistant oauth mode <provider-key> --set "managed"|"your-own"
Troubleshooting
Permission / Insufficient Scope Errors
If an API request returns a 403 Forbidden, 401 Unauthorized, or a message about missing scopes, the connection likely doesn't have the scopes needed for that action. See Updating Scopes for how to disconnect and reconnect with the required scopes.
Reference
For detailed information on the following topics, see the reference files:
