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

# Foundry integrations

> Connect external tools to Foundry from your organization settings using API keys, bearer tokens, basic auth, or custom OAuth providers for Ravenna workflows.

An integration is a connection to an outside tool. Each integration stores the sign-in details so your functions can talk to the tool, plus a link to the tool's documentation so Foundry knows what the tool can do.

Integrations are managed by **organization admins** in Settings. Once an integration is set up, anyone using Foundry can build functions on top of it.

***

## Where integrations live

Foundry uses two settings pages:

* **Settings → Integrations**. Create and manage custom API integrations. They appear in the **Custom** category alongside Ravenna's built-in integrations.
* **Settings → OAuth Providers**. Register OAuth providers that end users connect their own accounts to.

You can also see the list of integrations available to Foundry inside the Foundry app itself, under the **Integrations** tab in the left sidebar. The **New Integration** button there links straight to Settings.

***

## Custom API integrations

Use these for any tool with an API that uses a static credential (API key, bearer token, basic auth) or no auth at all.

### Create one

<Steps>
  <Step title="Open Settings → Integrations">
    Select the **Custom** category, then click **New Integration**.
  </Step>

  <Step title="Basics">
    Fill in the API name, an optional description and logo, a category, and a link to the tool's documentation.

    <Info>
      The best documentation link is one that goes straight to the API reference, not the marketing homepage. If the tool has an OpenAPI or Swagger link, use that.
    </Info>
  </Step>

  <Step title="Research">
    Foundry reads the documentation to learn how the tool works, including pagination, auth methods, rate limits, error handling, and versioning. You'll see live progress for each of those steps. This usually takes under a minute.
  </Step>

  <Step title="Auth">
    Select the sign-in type and fill in the credentials. The wizard supports **API key**, **Bearer token**, **Basic auth**, and **No auth**. You can also add **default headers** that should be sent with every request from this integration. These are useful for things like a tenant or account header.
  </Step>

  <Step title="Review and save">
    Review your settings, then save. The integration is now available to Foundry functions.
  </Step>
</Steps>

### Edit or delete later

From **Settings → Integrations**, click any custom integration to open its details. You can edit the basics and authentication, re-run docs research, or delete the integration. You'll need to remove or unpublish any functions using it before you can delete it.

<Info>
  Credentials are stored in Ravenna's secure vault. They're only used when a function runs and they're never shown to the AI that writes your function code.
</Info>

<Callout icon="book-open" color="#7C3AED">
  For a step-by-step walkthrough of the custom integration wizard, see [Set up a custom API integration](/guides/how-to/foundry/setup-custom-api) in the Foundry guide.
</Callout>

***

## OAuth providers

Use these for tools where end users sign in with their own account, for example Google, Microsoft, or Salesforce. Each user who runs a function connects their account once, and the function executes as that account.

### Register a provider

<Steps>
  <Step title="Open Settings → OAuth Providers">
    Click **Add Provider**.
  </Step>

  <Step title="General">
    Give the provider a name, a slug (used internally), an optional description and logo, and the base URL and docs URL for the API.
  </Step>

  <Step title="OAuth">
    Enter the provider's authorization URL, token URL, scopes, client ID, and client secret. Expand **Advanced** if the provider has non-standard requirements (extra parameters, alternate credential delivery, or a non-`Bearer` API auth header). See [Advanced OAuth settings](#advanced-oauth-settings) below.
  </Step>

  <Step title="Research and save">
    Foundry researches the docs URL the same way it does for custom API integrations, then saves the provider. It's now enabled for the org and shows up in the **Custom** category of **Settings → Integrations**, where users can connect their accounts.
  </Step>
</Steps>

### Connect fields on Ravenna-provided providers

Some Ravenna-provided OAuth providers need a per-user value (a workspace subdomain, an account region, a per-tenant API host) to complete the OAuth flow. When you connect an account to one of those providers, Ravenna opens a **Connect {'{provider name}'}** dialog and asks for the required values before starting sign-in. Each field shows a label, an optional placeholder, and one-line help text explaining where to find the value.

The **Connect** button stays disabled until every required field has a value. Ravenna then URL-encodes each value, substitutes it into the provider's URLs, and starts the OAuth flow. It stores the values alongside the connection and reuses them on every API call from that user's functions.

<Info>
  Connect fields only appear when a provider template defines them — most providers don't. Custom OAuth providers you register from **Settings → OAuth Providers** don't use connect fields.
</Info>

You can disable or delete providers at any time from **Settings → OAuth Providers**.

### Advanced OAuth settings

Most providers work with just the basic fields above. Expand **Advanced** on the OAuth tab when a provider deviates from the OAuth 2.0 defaults. Foundry auto-expands the section when you edit a provider that already has non-default values.

| Field                            | When to use it                                                                                                                                                                                                                                                                                          | Default              |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Grant type**                   | Which OAuth 2.0 flow Foundry uses to obtain tokens. Keep **Authorization Code** when each user signs in with their own account. Switch to **Client Credentials** for a server-to-server provider that uses a single shared machine credential for the whole org. See [Grant types](#grant-types) below. | Authorization Code   |
| **Auth URL params (JSON)**       | Extra query parameters appended to the authorization URL. Google needs `{"access_type": "offline", "prompt": "consent"}` to issue refresh tokens.                                                                                                                                                       | None                 |
| **Token exchange params (JSON)** | Extra parameters merged into the token request body. Use for provider-specific fields the OAuth 2.0 spec doesn't define.                                                                                                                                                                                | None                 |
| **Credential delivery**          | How the client ID and secret are sent to the token endpoint. **Authorization Header** uses HTTP Basic auth (most providers). Switch to **Request Body** if the provider expects `client_id` and `client_secret` in the form body instead.                                                               | Authorization Header |
| **Token exchange format**        | Content-Type of the token request body. **Form URL-encoded** is the OAuth 2.0 default. Switch to **JSON** for providers that require it.                                                                                                                                                                | Form URL-encoded     |
| **API auth header scheme**       | The scheme prefix Foundry uses in the `Authorization` header when calling the provider API with the access token. Set this when a provider rejects the standard `Bearer` prefix — Discord bot tokens, for example, use `Bot`.                                                                           | `Bearer`             |

<Info>
  The API auth header scheme only changes the prefix Foundry sends with API calls (for example `Authorization: Bot <token>` instead of `Authorization: Bearer <token>`). It doesn't change how the token itself is obtained.
</Info>

### Grant types

Foundry supports two OAuth 2.0 grant types. Pick the one that matches how the third-party API expects to be called.

**Authorization Code** is the default and the right choice for any provider where each user should act as themselves — Google, Microsoft, Salesforce, GitHub, and most consumer APIs. Each user connects their own account from **Settings → Integrations**, and Foundry runs functions as the connected user. Tokens refresh automatically using the stored refresh token.

**Client Credentials** is a server-to-server flow with no user redirect. Foundry exchanges the client ID and client secret directly for an access token, and every function call uses that same machine credential. Pick it when the provider issues an org-level token rather than per-user tokens — for example, an internal API that authenticates the whole organization with a single service account.

When you choose Client Credentials, the **Authorization URL** field is no longer required. The connect step doesn't open a sign-in page either: clicking **Connect** in **Settings → Integrations** fetches a token immediately and reuses it for every user. Tokens are re-fetched in place when they expire, since there's no refresh token.

<Info>
  Client Credentials is only offered for organization-owned OAuth providers, since the credential is shared across everyone in the org. Built-in Ravenna providers stay on Authorization Code.
</Info>

### Connect an account

Once a provider is registered, each user connects their own account by going to **Settings → Integrations**, finding the provider in the **Custom** category, and clicking through the standard OAuth sign-in flow. Tokens refresh automatically.

For Client Credentials providers, the connect step is a single click rather than a sign-in flow, and any user in the org who runs a function on the integration uses the same shared token.

<Callout icon="book-open" color="#7C3AED">
  Need help registering a provider? The Foundry guide has end-to-end walkthroughs for [Google Cloud](/guides/how-to/foundry/setup-oauth/google-cloud), [GitHub](/guides/how-to/foundry/setup-oauth/github), and [DocuSign](/guides/how-to/foundry/setup-oauth/docusign), plus a [shared overview](/guides/how-to/foundry/setup-oauth/overview) you can adapt to any provider.
</Callout>

***

## Managing integrations

* **Edit** to update sign-in details, the base URL, or the docs URL.
* **Re-research** to make Foundry re-read the documentation if the API has changed.
* **Delete** to remove the integration. Remove or unpublish any functions using it first.

<Callout icon="link" color="#6B7280">
  Ready to build? Learn how to [create a function](/documentation/automate/foundry/actions).
</Callout>