> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a custom OAuth app

> What you need to register a custom OAuth provider in Foundry for Ravenna integrations, plus end-to-end walkthroughs for Google Cloud, GitHub, and DocuSign.

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.

If the provider you're connecting uses a single machine credential for the whole org instead of per-user sign-in, register it with the **Client Credentials** grant type. See [Grant types](/documentation/automate/foundry/integrations#grant-types) for when to use each flow.

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.

<Callout icon="link" color="#6B7280">
  Reference: [Integrations → OAuth providers](/documentation/automate/foundry/integrations) in the main docs covers the field-by-field behaviour.
</Callout>

***

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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).
  </Step>

  <Step title="Connect an account">
    From **Settings → Integrations → Custom**, click the new provider and complete the sign-in flow. You only do this once per user.
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.

<CardGroup cols={2}>
  <Card title="Google Cloud" icon="google" href="/guides/how-to/foundry/setup-oauth/google-cloud">
    Google Workspace, Calendar, Drive, Gmail. The most common starting point.
  </Card>

  <Card title="GitHub" icon="github" href="/guides/how-to/foundry/setup-oauth/github">
    Issues, pull requests, repositories. Uses a slightly different OAuth flavour for organisation-owned apps.
  </Card>

  <Card title="DocuSign" icon="file-signature" href="/guides/how-to/foundry/setup-oauth/docusign">
    Send envelopes, check signing status, fetch signed documents. The OAuth flow has a per-account base URL gotcha the walkthrough covers.
  </Card>
</CardGroup>

<Callout icon="link" color="#6B7280">
  Stuck on something not in these walkthroughs? Common OAuth errors are covered in [Tips & troubleshooting](/guides/how-to/foundry/tips-and-troubleshooting).
</Callout>