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.
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
1
Open Settings → Integrations
Select the Custom category, then click New Integration.
2
Basics
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.
3
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.
4
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.
5
Review and save
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 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
1
Open Settings → OAuth Providers
Click Add Provider.
2
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.
3
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 below.4
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.
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 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.
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.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.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.Need help registering a provider? The Foundry guide has end-to-end walkthroughs for Google Cloud, GitHub, and DocuSign, plus a shared overview you can adapt to any provider.
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.