Skip to main content

Integrations

An integration represents one external service, such as GitHub, Jira or a model provider. It holds:

  • Secrets: credentials such as API keys and tokens, stored encrypted in a secrets vault.
  • Environment variables: non-sensitive configuration such as a region or base URL.
  • Allowed URLs: every URL the integration is permitted to call.
  • Operations: the specific requests functions may make with the integration's credential (see below).

Functions link to integrations to reach external services, and models link to them for their API keys. You manage integrations under Resources → Integrations, in a tree called the Integration Library.

Agent ──calls──▶ Function ──linked to──▶ Integration ──credential──▶ External service
                                         (secrets, allowed URLs,
                                          operations)

Scope​

Integrations belong to a project and are visible to its members. Integrations aren't shared between projects automatically. To use the same service in another project, create (or copy) the integration there, or carry it across with a promotion (see Promoting Between Projects).

Platform-provided integrations, installed from a platform template, show Managed by platform — read only.

Secrets​

Each secret is a name and a value. The value is masked as ***** after saving: you can replace it or delete it, but the app never shows it again. Keep your own copy somewhere safe.

  • Name secrets after what the consumer expects. Model configs look for names such as api_key. MCP stdio servers receive each secret as an environment variable of the same name.
  • Copying an integration does not copy secret values. Re-enter them on the copy.
  • Agents reading secrets at runtime are checked against the integration's access rules and risk settings, and every decision is logged.

Environment variables​

Key/value pairs for configuration that isn't secret. They're passed alongside secrets: MCP stdio servers receive them as environment variables.

Allowed URLs and operations​

Allowed URLs lists every base URL the integration may call, for example https://api.github.com, https://uploads.github.com. A service that uses a separate upload or token host needs each one listed.

An operation is a named, declared request against one of those URLs: an HTTP method, a relative path template such as /repos/{owner}/{repo}/pulls, and the parameters a caller may supply. Operations are what make brokered calls possible:

  • A function calls an operation by name with capabilities.call(...). The platform adds the credential and makes the request, so the function never holds the secret.
  • The host always comes from the integration, so an operation can't send the credential anywhere else.
  • Undeclared query and body parameters are dropped. Values an operation pins can't be overridden.
  • A function can only call operations granted to it under Allowed Operations.

Allowed URLs must be set before an integration can declare operations. The app lists and uses operations (in Wrap an integration operation and Allowed Operations), but you declare them through the API or get them from a platform template. See Declaring Integration Operations.

How the credential is presented​

By default a brokered call sends one secret as Authorization: Bearer <secret>. Through the API, an integration can declare a different scheme in its auth field:

SchemeHeader sentSecrets
bearer (default)Authorization: Bearer <secret>1
basicAuthorization: Basic base64(<first>:<second>), for example Jira Cloud's email and API token2
headerA header you name, with an optional literal prefix such as ApiKey 1

OAuth-brokered integrations​

Some integrations sign each user in to the provider with OAuth instead of storing a shared key. People connect their own account under Settings → Connected Accounts, and agents acting for them use only that person's grants. These integrations are normally installed from a template or the Marketplace. See Connected Accounts.

When such an integration is open, the Details tab shows Allow delegated-autonomous connections. Turning it on lets a project administrator connect a shared service connection that scheduled or autonomous runs use when no user is present. Those runs act with that connection's access, so enable it only if you intend unattended jobs to use it.

Access grants for agents​

Agents run with a service identity. An integration's access list records which agent identities may use it. Access grants are managed through the API and the platform's MCP tools by platform administrators (grant_integration_access, revoke_integration_access, list_integration_access). Depending on platform configuration, a missing grant is either logged for audit or enforced. Human users in the project keep project-wide access.

Integration page tabs​

TabContents
OverviewReach, access grants and secret counts at a glance.
DetailsThe editable fields, icon, Secrets and Environment Variables.
TopologyA graph of what is connected to this integration.
RiskRisk level, data classification and related governance fields. An integration can require a justification for secret reads.