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

# Connect an external service

> Connect Forge outbound to a vendor such as Linear, GitHub, Slack, 1Password, or Pipedream through Virtual Keys and capability provider records. Not an External App (the inbound OAuth client).

Last updated 2026-11-11

·
applies to 2026-11-07

·
main

> [!WARNING]
>
> **This page is about the OUTBOUND direction and does not involve the External App primitive.** "External App" in Forge means one specific thing: an **inbound** OAuth2 client — a partner application that authenticates at `POST /oauth/token` and calls Forge. This page is about the opposite arrow: Forge calling out to a vendor. The two share no schema, no credential, and no console page.
>
> * Registering a partner app that calls Forge → **[External Apps (operator guide)](https://docs.gloo.com/forge/console/platform/external-apps)** and the [External Apps API](https://docs.gloo.com/forge/reference/http-api/externalApps).
> * Giving yourself a key to call Forge from an AI host or a script → a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md). To choose between an External App and a Personal key, see [Choose a credential](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential).
> * Connecting Forge to a vendor it calls → this page.
>
> Note the naming hazard in the outbound direction too: for authorization-code vendors, the console calls the vendor client registration an **OAuth application** (Platform -> Vendors). That is still outbound — a credential Forge presents to a vendor — and is not an External App. See [Vendors (operator guide)](https://docs.gloo.com/forge/console/platform/vendors).

This guide is for the operator connecting Forge **outbound** to an external service — Linear, GitHub, Slack, 1Password, Pipedream, and the others on the road map. The thing you are doing is twofold: provisioning a credential, and (for capability-backed integrations) configuring the **capability provider** to route resolution to that vendor.

There are two credential shapes, depending on how the vendor authenticates. Vendors that take a static secret (an API key or personal token) use the **Virtual Keys** system described below. Vendors that require authorization-code OAuth instead use an **OAuth application** + **connected account** + **credential binding**, operated from Platform -> Vendors — see [Vendors (operator guide)](https://docs.gloo.com/forge/console/platform/vendors) for that path. Either way, runtime consumers resolve one ordinary Forge Credential.

For the architectural picture of the provider model — why every external dependency is a swappable capability — see [Composable capabilities](https://docs.gloo.com/forge/concepts/capabilities.md). For the full provider catalog, see the capability inventory. This page is the operator's setup guide.

When to reach for something else

If you are an engineer adding a brand-new external service that the platform doesn't yet model — a different LLM proxy, a third secrets store, a new ticketing system — that is engineering work to add a capability provider in the Forge codebase, not this page. This page is for connecting Forge to a service the platform *already supports* (Linear today, more coming). If your need is "I want my agent to call this one API once," that's a [tool](https://docs.gloo.com/forge/concepts/tool-registry.md) — not a capability provider. Capability providers are for cross-cutting integrations where multiple agents and workflow nodes resolve the same credential or capability.

***

## The two-layer model

External integrations have two layers, and you almost always touch both:

VENDOR CONNECTION — TWO LAYERS

<ol aria-label="VENDOR CONNECTION — TWO LAYERS" />

**Virtual Keys** are the credential layer. A Virtual Key (VK) is a named credential record — it knows what it's for (`tool_call`, `capability_provider`, `inference_provider`, `external_tool_identity`) and points at an encrypted secret (never plaintext in Convex storage). For agent **tool calls**, dispatch follows the agent's VK chain: the runtime looks up the active VK for `(agent, tool)`, follows it to the underlying `toolCredentials` row, checks the row's approval state, and returns the secret on hit. For **inference**, **capability provider**, and **external tool identity** purposes, the resolver walks an ownership scope hierarchy (user → agent → project → factory → org unit → system) and returns the first matching active VK.

**Capability providers** are the routing layer. Every platform-level external dependency — LLM inference, secrets, project management, embeddings, GitHub, observability — is modeled as a typed capability interface. At runtime, Forge resolves each domain's active provider from its enabled provider records: an enabled provider an operator configured comes first, and a domain's pinned foundation provider, where it has one, serves when no other provider is enabled. A domain with neither fails with a domain-specific error. Operators configure this in **Platform → Capabilities**; application code never changes.

For tool-level integrations (a single tool calling a single API with a credential), only the credential layer matters. For platform-level integrations (project management across factories, secrets across the deployment), both layers matter.

***

## How credentials resolve at runtime

Resolution depends on the credential's purpose. Tool calls and the other VK purposes follow different paths.

### Tool calls — agent VK chain

When an agent in a workflow runs a tool that needs a credential, dispatch follows the agent's VK chain. There is no scope walk:

```
Agent + Tool
  ↓
Active virtualKey row for (agent, tool)
  ↓
Linked toolCredentials row
  ↓
Approval state check → decrypted secret
```

If no active VK exists for the `(agent, tool)` pair, dispatch surfaces a "no credential reachable" state — a Trust Fabric admin must approve a `toolCredentials` row and issue a VK for the agent before the tool can run. This is the model the workflow builder's tool-credential widget shows.

The `toolCredentials` row itself **owns** at one of `system`, `org_unit`, `factory`, or `project` scope (where the credential lives in the org hierarchy), but per-agent access is granted through VK issuance — not by walking the workflow's scope chain.

### Inference, capability provider, and external tool identity — scope walk

For VKs whose purpose is `inference_provider`, `capability_provider`, or `external_tool_identity`, the resolver walks scopes in priority order and returns the first active match:

```
User scope
  ↓
Agent scope
  ↓
Project scope
  ↓
Factory scope
  ↓
Org unit (department) scope  ← walks up the org tree
  ↓
System scope (global default)
```

This lets you set a system-wide API key as a default while allowing per-user credentials to override for personal integrations.

Inference credentials follow their provider resolution contract. See [Credentials](https://docs.gloo.com/forge/console/platform/credentials.md) for the operator controls and [Define an agent](https://docs.gloo.com/forge/build/define-an-agent.md) for how an agent's tools and credentials are assembled.

***

## Provision a credential — the internal store

By default, Virtual Keys live in Convex with per-deployment encryption. Secrets are encrypted at the application layer before being written to the database; no plaintext credentials ever touch document storage.

Provision a credential in the Forge Console from the vendor's connection: open **Platform → Vendors**, open the vendor and select **Provision account** on the connection's row (you need `credentials:write`). Or provision it over the API with `POST /api/v3/connection-credentials/provision` (MCP `provisionConnectionCredentialAdmin`). The call creates the vendor connection's credential at a scope, or rotates it in place when one exists:

1. **Name the vendor and connection.** `vendorKey` is the vendor (for example `linear`) and `connectionName` names this connection.
2. **Pick a scope.** `scope` is `{ "type", "id" }`, where `type` is `system` or `org_unit` and `id` names that scope; `sharedWithDescendants` shares an org-unit credential with the units below it. `environment` is `production` or `sandbox`.
3. **Provide the secret.** `fieldValues` is a list of `{ "key", "value" }` pairs for the vendor's credential fields. It is encrypted before write.
4. **Find the credential ID.** The response reports `provisioned` and `mintedSecrets`, not an ID. List credentials with `GET /api/v3/connection-credentials` to find it; the approve, verify and revoke calls take it. Agent code resolves the credential by vendor and scope, not by ID.

The call needs `credentials:write` and a Personal key or a platform API key; an External App token is refused. The internal Convex store is the default when no external provider is configured. 1Password is an optional enhancement for organizations that require credentials to live outside the application database.

***

## Prepare the disabled 1Password Secret-store provider

Forge has one durable `1password` Secret-store provider with Service Account and Connect transports. The provider is currently disabled, unpinned, and off-chain; Forge remains the only active writer. Preparing deployment configuration does not activate 1Password or migrate a Secret.

The supported runtime baseline is one shared Service Account authorized at creation for the pre-created development, staging, and production vaults. Grants are immutable, so replace an existing staging-only account that lacks the full approved vault set. Separate per-environment identities are optional hardening.

* Production receives the shared token plus its production `ONEPASSWORD_DEFAULT_VAULT`.
* Staging receives the shared token plus its staging vault and is the only Service Account canary target.
* Persistent development may receive the shared token plus its development vault only after that deployment is explicitly registered.
* Preview receives neither the shared token nor a vault. Local receives neither by default.

Every store, resolve, rotate, and revoke action validates `ONEPASSWORD_DEFAULT_VAULT` before creating an SDK client or sending a Connect request. Writes use it, canonical locators must match it, and bare item IDs expand only through it. There is no provider option, request argument, Secret field, or operator override for vault selection.

### Deployment configuration

1. **Create the approved vault set and runtime identity.** Grant only view items, view/copy concealed values, create items, edit items, and archive items.

2. **Set protected deployment values** through the approved secret-management channel:

   | Variable | Description |
   | - | - |
   | `OP_SERVICE_ACCOUNT_TOKEN` | Shared runtime Service Account token; absent in preview/local by default |
   | `ONEPASSWORD_DEFAULT_VAULT` | This deployment's sole 1Password vault authority |
   | `ONEPASSWORD_CONNECT_HOST` | Connect base URL, only when choosing the alternative Connect transport |
   | `ONEPASSWORD_CONNECT_TOKEN` | Connect token, only when choosing the alternative transport |

3. **Keep the provider disabled.** The source binding is `1password-service-account` / `onepassword/service-account`; `1password-connect` / `onepassword/connect` remains the compatible alternative.

4. **Verify staging only** with the documented deployed Service Account canary before a later activation PR. Do not run a production canary during setup.

Field-tested status

Readiness does not mean activation. Forge remains the active Secret store, and current preview/local 1Password calls fail closed before transport.

### Multi-provider deployments

Secret references retain their owning provider so owner-routed operations never fall back across stateful stores. New writes continue to select Forge while 1Password is disabled.

### Transport adapters

The `1password` provider has two transport adapters. Both are disabled.

| Adapter | Vendor connection | Posture |
| - | - | - |
| `1password-service-account` | `onepassword/service-account` | Default source binding |
| `1password-connect` | `onepassword/connect` | Compatible alternative; also needs `ONEPASSWORD_CONNECT_HOST` and `ONEPASSWORD_CONNECT_TOKEN` |

Connect applies the same deployment-vault validation and has no separate vault override. The vault
check constrains Forge's routing; it does not narrow the vault grants the runtime identity holds.

### Runtime identity per environment

| Environment | Token | Deployment vault | Notes |
| - | - | - | - |
| Production | Shared runtime token | Production vault | Provider remains disabled |
| Staging | Shared runtime token | Staging vault | Only Service Account canary target |
| Persistent development | Shared runtime token, only after registration | Development vault | No identity until a persistent deployment is explicitly registered |
| Preview | None | None | Calls fail closed before transport |
| Local | None by default | None by default | Forge storage remains active |

A shared identity has a wider blast radius, coupled rotation and a shared audit identity. Splitting
it into per-environment identities later does not change stored locators. A canonical
`op://<vaultId>/<itemId>/credential` locator must name the deployment vault exactly; a legacy bare
item ID expands only through that vault. Missing or invalid deployment configuration fails closed
before any request reaches 1Password.

### Migrate a Secret to 1Password

A Forge administrator can move one approved, ordinary Forge-owned Secret to 1Password while the
provider stays disabled for new writes. The migration is deliberate and reversible until committed:

1. **Preview** the Secret and record its exact version and consumer count.
2. **Migrate** it with a fresh operation ID and an explicit attestation that it is not a tier-zero
   Secret. Verify that the Credentials consuming it still work.
3. **Roll back** if needed, within a seven-day retention window, with a different operation ID and
   the current exact version and count. Forge becomes canonical again; any cleanup of the
   1Password item that remains is reconciled before the migration closes.
4. **Commit** to accept a retained migration permanently. Commit requires a fresh operation ID, the
   migration's operation ID, the exact version and count, and an explicit irreversible confirmation.
   It re-verifies every consumer, archives the Forge copy and leaves 1Password canonical. If source
   cleanup remains required, rotate, revoke and rollback stay blocked until an operator reconciles
   it.

A migration supports at most 64 Credential-field links. Ordinary rotate and revoke are blocked
while rollback retention or cleanup is active. If verification after the switch fails and Forge
restores itself automatically, a separate `secret_migration_compensated` governance event records
it; it contains no locator, digest, value or raw provider error. A successful staging canary is
readiness evidence, not authority to activate the provider. Activating 1Password for new writes is
a separate, audited governance change.

### Operational constraints

* Owner-routed stateful operations never fall back to a different provider.
* A migration keeps exactly one canonical binding; the retained Forge value is private rollback
  material, never a read replica, and ordinary reads never fall back to it.
* A provider write that returned no locator is never retried blindly.
* Forge keeps no plaintext Secret cache or environment mirror.
* Neither transport adds automatic retries; Connect keeps its bounded request timeout.
* Errors and metrics exclude tokens, Secret values, digests, raw vendor messages and cross-vault
  locator content.
* An approved recovery copy of the shared token is a recovery artifact, not a second runtime source
  or a routing override.

***

## Wire a capability — Linear (project management)

Linear is the canonical case for a capability-backed external app. The `project_management` domain's foundation provider is Forge's own task store; switching to Linear means one vendor credential plus one enabled provider record.

### What the Linear adapter supports today

| Operation | Status |
| - | - |
| List projects | Available |
| Get project | Available |
| List tasks (issues) | Available |
| Get task (issue) | Available |
| Create task | Available when a Linear team id is configured |
| Update task | Available when a Linear team id is configured |
| Create project | Not supported |
| Status / priority mapping | Available |

Writes need a team

Task creation and updates need a Linear team id, set as `teamId` in the `project_management` capability's options or as the `LINEAR_TEAM_ID` environment variable on the deployment; without one, the adapter refuses the write with an error that names the missing team. Creating projects is not supported. The integration has not yet been verified end-to-end, so treat it as experimental until you have tested it against your workspace.

### Connecting Linear

1. **Generate a Linear API key** in your workspace: *Settings → API → Personal API keys* (or use an OAuth token for per-user credentials).

2. **Provision the credential as a Virtual Key**, scoped appropriately:
   * **System** — one key for all agents across the workspace.
   * **Org / factory** — a key for a specific team's factory.
   * **User** — a per-user Linear token for personal-agent access.

3. **Enable the provider.** Store the API key on the Linear vendor's `api` connection: open **Platform → Vendors → Linear**, select **Provision account** on the `api` connection's row, choose the scope, enter the key and select **Provision account** again to save. Then open **Platform → Capabilities → Providers → Linear** and turn on the **Enable provider** switch, which needs `platform:manage`. Linear ships disabled. A deployment that sets the `LINEAR_API_KEY` Convex environment variable seeds the connection's key on first boot, but the record still has to be enabled.

4. **Verify** by running a workflow node that has the `project_management` tool set enabled — it should now read from Linear.

### Status and priority mapping

The adapter translates Linear's state model into Forge's canonical task model. The adapter applies this mapping:

| Linear state type | Forge `TaskStatus` |
| - | - |
| `triage`, `backlog` | `BACKLOG` |
| `unstarted` | `READY` |
| `started` | `IN_PROGRESS` |
| `completed` | `COMPLETE` |
| `canceled` | `CANCELLED` |

| Linear priority | Forge priority |
| - | - |
| 0 (no priority) | `medium` |
| 1 (urgent) | `urgent` |
| 2 (high) | `high` |
| 3 (medium) | `medium` |
| 4 (low) | `low` |

### When Linear is not enabled

While the `linear` record is disabled, project-management calls use Forge's own task store, the domain's foundation provider. That is the configured default, not a silent failover: once Linear is the active provider, a failing Linear call returns an error rather than switching back to Forge.

***

## The wider provider catalog

Linear is one of many supported integrations. Forge defines 20 capability domains. Some have a **foundation provider** that Forge pins: it stays in the domain's provider records, ordered after any provider an operator enables, and serves the domain when none is enabled. The others have no pinned foundation. Most of them stay **listed, unconfigured** and fail with a domain-specific error until an operator enables a real provider. `secrets_store` is the exception: Forge's own store ships enabled, so it serves that domain from the start without being pinned. No domain silently falls back to a stand-in.

| Domain | What it provides | Foundation provider |
| - | - | - |
| `inference` | LLM inference for agent reasoning, chat and structured output | None |
| `embeddings` | Vector embeddings for search, agent memory and knowledge retrieval | None |
| `llm_fallback_chains` | Ordered model failover when a primary model is unhealthy | Forge |
| `source_control` | Git host integration: branches, pull requests, statuses, file contents | None |
| `coding_agent` | A CLI coding harness run against a repository inside a governed sandbox | None |
| `org_structure` | Departments, teams and people, imported from an HRIS or kept in Forge | None |
| `project_management` | Projects, tasks and assignments, kept in Forge or synced from Linear or Asana | Forge |
| `secrets_store` | Credential storage for tool authentication and integration secrets | None pinned; Forge's store ships enabled and serves by default |
| `blackboard` | Scoped task-state documents agents share across steps | Forge |
| `file_hosting` | Blob storage for run artifacts, attachments and outputs | Forge |
| `notifications` | Outbound notification routing to the bell, Slack, email and more | Forge |
| `human_interaction` | Surfaces that present approvals and questions and collect a person's answer | Forge |
| `sandbox` | Isolated, ephemeral VMs for running agent-generated code | Vercel |
| `network` | Audited outbound HTTP for procedures | Forge |
| `publish` | Terminal delivery of a workflow's output: storage, a channel, Slack, Drive, email | Forge |
| `chat_syndication` | Relay between Forge chat channels and external chat platforms such as Slack | None |
| `telemetry_export` | Export of platform events to security and observability sinks | None |
| `knowledge` | The scoped organizational knowledge store | Forge |
| `synchronized_knowledge` | External systems Forge synchronizes knowledge from | None |
| `typed_judgments` | Typed evaluation of caller-supplied closed choices for procedures | None |

**Platform → Capabilities** shows each domain's readiness and the adapters available for it. External providers are enabled through provider records, with their credentials on a vendor connection; setup follows the same pattern as Linear (store the credential → enable the record → verify). See [Composable capabilities](https://docs.gloo.com/forge/concepts/capabilities.md) for how resolution works.

A brand-new integration the platform doesn't yet model is engineering work in the Forge codebase.

Convex is the source of truth

When an external provider is connected, data flows bidirectionally — but Convex always holds a canonical copy. Disconnecting an external provider doesn't delete your data, and you're never locked into a vendor's export format. See the [system overview](https://docs.gloo.com/forge/architecture/system-overview.md) for where platform state lives.

***

## What you should double-check before going live

* **Credential scope is correct.** A Linear token at user scope won't be reachable by a factory-scoped agent without explicit grants. Match the scope to who needs the credential.
* **Disabling the provider does what you expect.** Disable the record in a test deployment. In a domain with a foundation provider (such as `project_management`), confirm calls go back to the foundation. In a domain without one, confirm the call site surfaces the domain-specific error. Forge never switches providers in the middle of a failing call.
* **Audit log shows the resolution.** Every credential lookup is logged. Spot-check that the right Virtual Key was resolved for the right call.
* **Rotation is wired.** If the credential rotates (Linear token expiry, OAuth refresh), the renewal path is in place. The internal store has straightforward update mutations; 1Password Connect carries renewal in the vault item itself.
* **Field-tested status matches your risk tolerance.** Linear and 1Password Connect both have implemented adapters that are not yet verified end-to-end. Keep the Forge foundation provider active in production until you've done your own integration testing.

***

## Do it over the API

Connecting Linear has an API path: store the credential, enable the provider, then check the provider's credential health. These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md), but not its `ACCESS_TOKEN`. That token is scoped for agents and dispatch, so each call below would answer `403`.

The three steps need these scopes:

| Step | Scopes |
| - | - |
| Store the API key | `credentials:write` |
| Enable the provider | `platform:manage` |
| Check the connection | `grants:read`, `policies:read`, `audit:read` |

Use one [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#static-keys) for all three. The first step refuses an External App token. Scopes only narrow what you hold, and only the **Platform admin** role holds `platform:manage`, so the key's owner needs Platform admin. When you create the key, tick **Include elevated permissions** (see [Approve and administer scopes](https://docs.gloo.com/forge/console/settings/personal-keys.md#approve-and-administer-scopes)), choose `credentials:write` and `platform:manage`, and choose the **Governance reader** preset for the three reads. Then set the key as the bearer:

```bash theme={null}
export FORGE_KEY="<your fmcp_ Personal key>"
```

An External App that holds Platform admin can run the last two steps with a token minted with `scope=platform:manage grants:read policies:read audit:read`, but it cannot store the key.

**1. Store the API key**

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/connection-credentials/provision" \
  -H "Authorization: Bearer $FORGE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: linear-api-credential-v1" \
  -d "{\"vendorKey\": \"linear\", \"connectionName\": \"api\", \"fieldValues\": [{\"key\": \"apiKey\", \"value\": \"$LINEAR_API_KEY\"}]}" \
  | jq '.data'
```

This needs `credentials:write` and accepts only a Personal key or a platform API key, not an External App (see [Choose a credential](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential)). With no `orgUnitId` or `scope`, the credential is stored at the system scope; send `orgUnitId` to store it for one company. The call creates the credential or rotates it in place. Keep the key out of an agent's context: provision it over HTTP or in Console rather than through an MCP tool call.

**2. Enable the provider**

```bash theme={null}
curl -sS -X POST "$FORGE_BASE/api/v3/providers/linear/enable" \
  -H "Authorization: Bearer $FORGE_KEY" \
  -H "Idempotency-Key: linear-provider-enable-v1" \
  | jq '.data | {key, enabled, changed}'
```

This needs `platform:manage` at the platform scope; a credential whose grant covers only some org units gets `403` and nothing is written. Enabling an enabled provider answers `changed: false`.

**3. Check the connection**

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/providers/linear" \
  -H "Authorization: Bearer $FORGE_KEY" \
  | jq '.data | {enabled, capabilitiesServed, credentialHealth}'
```

This needs `grants:read`, `policies:read` and `audit:read` at the deployment root. Credential values, ids and scopes are never returned; `credentialHealth` reports resolution, approved and pending counts, and the last verification.

Over MCP, `forge_call_operation` enables the provider and `forge_call_read_operation` reads it; both are in the default `start` job. The host's credential needs the same scopes as the HTTP steps: `platform:manage` to enable, and `grants:read`, `policies:read` and `audit:read` to read.

```json theme={null}
{ "operationId": "enableProvider", "idempotencyKey": "linear-provider-enable-v1", "input": { "key": "linear" } }
```

```json theme={null}
{ "operationId": "getProvider", "input": { "key": "linear" } }
```

***

## See also

* [Tools and skills](https://docs.gloo.com/forge/concepts/tool-registry.md) — for tool-level integrations that read a Virtual Key
* [Composable Capabilities concept](https://docs.gloo.com/forge/concepts/capabilities.md) — the architectural why
* capability inventory — the full domain list with promotion notes
* [System overview](https://docs.gloo.com/forge/architecture/system-overview.md) — why Convex stays the source of truth
* [External Apps (operator guide)](https://docs.gloo.com/forge/console/platform/external-apps) — the INBOUND primitive this page is often confused with


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