The two-layer model
External integrations have two layers, and you almost always touch both: 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) 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 isinference_provider, capability_provider, or external_tool_identity, the resolver walks scopes in priority order and returns the first active match:
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 needcredentials: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:
- Name the vendor and connection.
vendorKeyis the vendor (for examplelinear) andconnectionNamenames this connection. - Pick a scope.
scopeis{ "type", "id" }, wheretypeissystemororg_unitandidnames that scope;sharedWithDescendantsshares an org-unit credential with the units below it.environmentisproductionorsandbox. - Provide the secret.
fieldValuesis a list of{ "key", "value" }pairs for the vendor’s credential fields. It is encrypted before write. - Find the credential ID. The response reports
provisionedandmintedSecrets, not an ID. List credentials withGET /api/v3/connection-credentialsto find it; the approve, verify and revoke calls take it. Agent code resolves the credential by vendor and scope, not by ID.
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 durable1password 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.
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
- Create the approved vault set and runtime identity. Grant only view items, view/copy concealed values, create items, edit items, and archive items.
-
Set protected deployment values through the approved secret-management channel:
-
Keep the provider disabled. The source binding is
1password-service-account/onepassword/service-account;1password-connect/onepassword/connectremains the compatible alternative. - Verify staging only with the documented deployed Service Account canary before a later activation PR. Do not run a production canary during setup.
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
The1password provider has two transport adapters. Both are disabled.
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
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:- Preview the Secret and record its exact version and consumer count.
- 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.
- 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.
- 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.
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. Theproject_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
Connecting Linear
- Generate a Linear API key in your workspace: Settings → API → Personal API keys (or use an OAuth token for per-user credentials).
-
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.
-
Enable the provider. Store the API key on the Linear vendor’s
apiconnection: open Platform → Vendors → Linear, select Provision account on theapiconnection’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 needsplatform:manage. Linear ships disabled. A deployment that sets theLINEAR_API_KEYConvex environment variable seeds the connection’s key on first boot, but the record still has to be enabled. -
Verify by running a workflow node that has the
project_managementtool 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:When Linear is not enabled
While thelinear 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.
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 for how resolution works.
A brand-new integration the platform doesn’t yet model is engineering work in the Forge codebase.
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 theFORGE_BASE set up in the Raw HTTP tab of the quickstart, 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:
Use one Personal key 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), choose credentials:write and platform:manage, and choose the Governance reader preset for the three reads. Then set the key as the bearer:
scope=platform:manage grants:read policies:read audit:read, but it cannot store the key.
1
Store the API key
credentials:write and accepts only a Personal key or a platform API key, not an External App (see 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
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
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.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.
See also
- Tools and skills — for tool-level integrations that read a Virtual Key
- Composable Capabilities concept — the architectural why
- capability inventory — the full domain list with promotion notes
- System overview — why Convex stays the source of truth
- External Apps (operator guide) — the INBOUND primitive this page is often confused with

