Skip to main content
OAuth is the right choice when each user should run a function as themselves. For example, “find a meeting on my calendar” or “create a GitHub issue in my account.” Instead of a single shared key, each end user signs in with their own account. Every OAuth setup follows the same shape regardless of provider. This page explains that shape so you know what to gather before you start. The walkthroughs at the bottom then take you through three specific providers end-to-end.
Reference: Integrations → OAuth providers in the main docs covers the field-by-field behaviour.

​
How OAuth works in Foundry

You’ll always work in two systems:
  1. In the third-party provider (Google Cloud, GitHub, DocuSign, etc.), you create an “OAuth app” or “OAuth client.” This tells the provider to trust Ravenna as an app that can ask users for consent.
  2. In Ravenna → Settings → OAuth Providers, you register the provider using the values the third party gave you. Foundry uses these to drive the sign-in flow.
After that, each user connects their own account once from Settings → Integrations, and any function built on the provider runs as the user who triggered it.

​
What you’ll need

Before you start any OAuth walkthrough, gather: From your Ravenna admin team
  • The OAuth callback URL for your deployment. For most customers this is https://app.ravenna.ai/api/integrations/foundry-oauth/callback; replace app.ravenna.ai with your custom domain if you use one.
From the third-party provider
  • Client ID and client secret. Issued when you create the OAuth app.
  • Authorization URL. Where users get sent to sign in (e.g. https://accounts.google.com/o/oauth2/v2/auth).
  • Token URL. Where Foundry exchanges the auth code for a token (e.g. https://oauth2.googleapis.com/token).
  • Scopes. The permissions your function will need. Start narrow; add more later.
  • API base URL. The root URL your function will call (e.g. https://www.googleapis.com).
  • Docs URL. A link to the API reference Foundry should research.
  • Any extra parameters. Some providers need custom params on the authorization or token requests (Google needs access_type=offline for refresh tokens; GitHub wants accept=application/json on the token exchange). The walkthroughs cover these.

​
The shape of every walkthrough

1

Create the OAuth app in the provider

Sign in to the provider’s developer console, create a new OAuth app, paste in Ravenna’s callback URL, and copy out the client ID and secret.
2

Pick your scopes

Decide what the function needs to do (read calendars, create issues, post messages) and pick the smallest set of scopes that covers it.
3

Register the provider in Ravenna

Go to Settings → OAuth Providers → Add Provider. Fill in the general details (name, slug, base URL, docs URL) and the OAuth details (URLs, scopes, client ID and secret, any extra parameters).
4

Connect an account

From Settings → Integrations → Custom, click the new provider and complete the sign-in flow. You only do this once per user.
5

Build a function on top

In Foundry, create a function, connect the provider on its Integrations tab, and describe what you want it to do.

​
Walkthroughs

Each walkthrough below is end-to-end. Pick the one closest to what you’re connecting. The steps are similar enough that you can usually adapt them to other providers in the same family.

Google Cloud

Google Workspace, Calendar, Drive, Gmail. The most common starting point.

GitHub

Issues, pull requests, repositories. Uses a slightly different OAuth flavour for organisation-owned apps.

DocuSign

Send envelopes, check signing status, fetch signed documents. The OAuth flow has a per-account base URL gotcha the walkthrough covers.
Stuck on something not in these walkthroughs? Common OAuth errors are covered in Tips & troubleshooting.
Last modified on June 4, 2026