Skip to main content
An integration of this kind is a named set of encrypted credentials plus configuration that agents and tools use to call an outside API. Two flavours share one model (Integration): known providers with a fixed credential shape (model and content APIs), and custom integrations for any HTTP API, optionally with an OAuth client-credentials flow. They live under the sidebar entry Integrations in the Settings group (/integrations), with a detail page per integration (/integrations/:integrationId) and the custom form at /integrations/generic/new and /integrations/generic/:integrationId/edit.

​
What it does

  • Known providers (availableProviders lists them with whether one is already configured): anthropic, openai, google, youtube, twitter, transcript_service (each needs api_key) and bedrock (needs AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION_NAME). LLM providers back agents’ default provider and model (providerModels lists a provider’s chat or embedding models); content providers back ingestion sources.
  • Custom integrations (provider_type custom): any display name, credentials as key-value pairs, and a config that HTTP API tools interpolate with {{key}} placeholders. An optional config.auth_flow describes an OAuth client-credentials token request (token_url, client fields); the executor fetches and caches the token per company and integration before calling the tool, and never caches a token fetched for an unsaved integration under test. A config.test_url lets Test connection call the API.
  • Safety on write and at runtime. URLs in the config must be literal https:// when they contain placeholders; a placeholder in the host is allowed only when every host placeholder resolves from a config key (never from a credential); the resolved host is checked against private and metadata ranges on save and again immediately before each request (safe_http). Headers are sanitised.
  • Lifecycle. createIntegration(providerSlug, displayName, credentials, config), updateIntegration (credentials can be replaced without resending config), status active or inactive, testIntegration and testCredentials (test before saving), deleteIntegration, with last_tested_at and last_error recorded.
  • Usage. integrationUsageStats(integrationId, startDate, endDate, days, timezone) reports consumption per integration for the usage pages.
  • Where credentials go. Credentials are encrypted at rest with a platform-managed key (the same mechanism as Slack, GitHub, Jira tokens, workflow webhook secrets and environment secrets) and decrypted only when a call is made.

​
Who can use it

  • Create, update, test a saved integration, test credentials before saving (createIntegration, updateIntegration, testIntegration, testCredentials): company admin (ability integration.manage_providers, listed under Settings -> Roles, /settings/roles).
  • List, read, see providers and models, usage statistics: any company member.
  • Delete: any company member (deleteIntegration checks membership only).
  • No plan or tier gate.

​
How to configure it

  1. Settings -> Integrations (/integrations) -> Add provider: pick the provider, enter its required fields, optionally Test credentials (testCredentials), then save (createIntegration).
  2. For a custom API: Integrations -> /integrations/generic/new: name, credentials, config keys (for example base_url), optional auth flow with its token URL, and a test URL; Test connection after saving (testIntegration).
  3. Reference the integration from an HTTP API tool’s execution config, or set it as an agent’s default provider.
  4. Rotate credentials with updateIntegration(credentials); disable with status: inactive rather than deleting when tools still reference it.

​
Limits and defaults

​
What it emits

  • Usage records attributed to the integration (and to agents, Slack users and cost tags through the usage pages).
  • last_tested_at / last_error on the integration.

​
Known gaps

  • Only client-credentials OAuth for custom APIs; no authorization-code (per-user) OAuth outside MCP servers.
  • Provider list is fixed in code; a new known provider is a code change, though any HTTP API can be added as custom.
  • Delete is open to any member while create and update need an admin.
  • No per-integration spend limit; budgets live at the billing level.

​
Customer-safe summary

Store the API keys your agents need, for the model providers you use and for any other HTTP service your team wants agents to call, in one place, encrypted. Test a connection before and after saving, rotate keys without touching the tools that use them, and see how much each integration is used. Custom integrations can hold a base URL and an OAuth token flow so your internal APIs work without exposing secrets to the agent.