> ## 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 Select the **Custom** category, then click **New Integration**. Fill in the API name, an optional description and logo, a category, and a link to the tool's documentation. 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. 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. 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. Review your settings, then save. The integration is now available to Foundry functions. ### 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. 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. 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. *** ## 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 Click **Add Provider**. Give the provider a name, a slug (used internally), an optional description and logo, and the base URL and docs URL for the API. 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. 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. ### 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. 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. 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` | The API auth header scheme only changes the prefix Foundry sends with API calls (for example `Authorization: Bot ` instead of `Authorization: Bearer `). It doesn't change how the token itself is obtained. ### 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. 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. ### 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. ### Reconnect a Foundry OAuth account A refresh token can eventually expire — Okta's default refresh token lifetime is a common example, and some providers also invalidate refresh tokens after long inactivity or a password change. When that happens, functions built on the integration start failing with auth errors even though the connection still exists. Use **Reconnect** to renew credentials in place. Reconnect re-runs the OAuth consent flow against the same connection, so the new tokens replace the old ones while everything else on the integration — its configured actions, its integration settings, and the automatic token-refresh schedule — is preserved. There's no need to disconnect first, and you don't have to re-link the integration to any functions that already use it. Reconnect is available in two places: * **In the Foundry builder.** Open the function, go to the **Authentication** tab, and click **Reconnect** next to the connected account. * **In the integration tile.** From **Settings → Integrations**, open the integration, and choose **Reconnect** from the actions menu on the connection row. Both entry points run the same in-place update: Ravenna reuses the connection's stored connect field values, sends you through the provider's consent screen, and writes the fresh tokens back to the existing connection. Reconnect is the recommended remedy when a refresh token expires (for example on an Okta connection). Disconnecting and reconnecting also works, but it drops the connection and requires re-linking any functions that reference it — Reconnect avoids that. Client Credentials providers don't show a **Reconnect** button in the integration tile's manage dialog. They don't require a user redirect, so tokens are re-fetched in place automatically when they expire — there's nothing to re-consent to. 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. *** ## Native credential bridges Some integrations you have already connected to Ravenna can share their credentials with Foundry actions directly. When a native bridge is available, you do not need to configure a separate Foundry integration. The action runs with the same OAuth token your Ravenna integration uses. **Available native bridges:** | Integration | What Foundry can access | | ---------------- | --------------------------------------------------------------------------------------------- | | Notion | Read and write pages, databases, and blocks in connected Notion workspaces. | | Jamf Pro | Query and manage devices, users, and policies in your Jamf Pro instance. | | Slack | Post messages, read channels, and interact with the Slack API using your connected bot token. | | Google Workspace | Access Google Drive, Calendar, and Admin APIs through your connected service account. | | Okta | Read and manage users, groups, and applications in your Okta org. | | FleetDM | Query device inventory and run live queries against enrolled hosts. | **Using a native bridge:** When you create or generate a Foundry action, select the connected integration from the integration picker. Foundry injects the integration's credentials into the sandbox at runtime. Your action code can call the third-party API directly without managing authentication. Native bridges use the same permissions your Ravenna integration has. If your Notion integration has read-only access, Foundry actions using that bridge also have read-only access. *** ## 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. Ready to build? Learn how to [create a function](/documentation/automate/foundry/actions).