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

# Generic and provider integrations

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

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

| Setting | Default | Where enforced |
| - | - | - |
| `provider_type` | `known` | model default |
| `status` | `active` | model default |
| URL scheme with placeholders | must start with literal `https://` | `validate_integration_config_urls` |
| Host placeholders | only from config keys, bare hostname, egress-checked | outbound HTTP guard |
| Auth-flow token cache | per company and integration id; unsaved integrations not cached | `http_executor.execute_auth_flow` |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.