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

# Vendors

> The registry of third-party systems Forge calls, the tools, procedures and providers that use each, and vendor OAuth: OAuth apps, connected accounts and credential bindings.

**Vendors** (`/platform/vendors`) is the **outbound** registry: the third-party companies *Forge calls out to* on behalf of users and workflows — Linear, Slack, Firecrawl, Planful, and the rest. It is the connective tissue that turns three otherwise-disjoint catalogs (Tools, Procedures, Capability providers) into one coherent answer: *these are the vendors Forge integrates with, and here is everything that touches each one.*

The **Vendors** sidebar entry has two tabs: **Vendors** and [Credentials](https://docs.gloo.com/forge/console/platform/credentials.md),
the credentials Forge presents to these vendors. A person who may read credentials but not vendors
(`credentials:read` without `vendors:read`) sees a **Credentials** entry in its place.

> [!NOTE]
>
> This page is only about the outbound direction. For the **inbound** direction — partner applications that authenticate to Forge and call its API — see [External Apps](https://docs.gloo.com/forge/console/platform/external-apps). The two are separate primitives with separate schemas and separate console pages, and the vocabulary on this page ("OAuth applications", "connected accounts") refers exclusively to credentials Forge presents *to* a vendor.

![Vendors](https://mintcdn.com/gloo-b243725a/Ndtg9NEpwGc2OULA/forge/images/console/platform/vendors-light.png?fit=max\&auto=format\&n=Ndtg9NEpwGc2OULA\&q=85\&s=7918458820479f30d62459a63ecbb2b9)

Vendors — Forge Console at `/platform/vendors`

## What you can do

* **Browse the registry**: every vendor Forge calls out to, with its approval status and what exposes it.
* **Approve a vendor**, or set its status, with `vendors:write`.
* **Open a vendor** for its reference links and the tools, procedures and capability providers linked to it.
* **Connect a vendor through authorization-code OAuth**, and read its Connection Client contract.

## Registry

The page is a single registry: a card per vendor showing its name, stable `vendorKey`, **approval status** (`Approved` / `Under review` / `Not approved` / `Deprecated`), category tags, and a count of how many tools, procedures, and capability providers expose it. Filter by approval status, or search by name, key, or tag. Click a vendor to open its detail page.

**Approving a vendor.** Approval status is operator-curated, not automatic — a vendor starts `Under review` until someone vets it. Operators holding the `vendors:write` permission get a one-click **Approve** button on any not-yet-approved card (and can set the full status from the detail header, below); everyone else sees the status as a read-only pill.

## Vendor detail (`/platform/vendors/[vendorKey]`)

* **Header** — logo, key, homepage, tags, and the approval status. Operators with `vendors:write` get a status selector here (approve / under review / not approved / deprecated); read-only users see a status pill.
* **Reference links** — outbound links to the vendor's MCP / API / SDK docs, Terms of Service, and pricing (all optional, by reference — Forge never stores vendor content).
* **What exposes this vendor** — three grouped lists of the linked tools, procedures, and capability providers, each row deep-linking across to that primitive's **Platform** catalog page.

## Connection Client contracts

Open a connection's **Client** panel to inspect the callable contract before writing a procedure.
For TypeSafe's `typed-judgments` connection, the panel shows the existing
`typed_judgments/evaluateChoices` capability: its input and result schemas, Python procedure call,
SDK success envelope, and request limits. The procedure builder discovers the same contract.

The input contains serialized JSON `state` and questions with explicit allowed options. Each
question supplies an `id`, `instructions`, and option `id`/`description` pairs. Supply the complete
eligible menu from the run-pinned catalog and approved policy; knowledge can inform selection but
cannot introduce an unlisted ID. Larger category trees need staged, complete menus rather than a
truncated list. The current limits are 16 questions, 255 options per question, 64 KiB of state, and
256 KiB for the complete request.

Use the Python call shown in **Client** through the existing procedure capability proxy. Its
success envelope is `{data, providerId}`; the operation result is under `data`. Declare
`typed_judgments` in the procedure's capabilities and
`apiIntegrations: [{vendorKey: "typesafe", connectionName: "typed-judgments"}]`. The published
workflow must bind that connection to the intended organization and hold the matching version
acting-for authority. Do not put the TypeSafe key in procedure code or call the vendor SDK directly.

This panel is static contract discovery. Reading it requires `vendors:read`; it neither reads a
credential nor grants execution or proves readiness. Store the API key as an organization-scoped
Credential on the TypeSafe connection, then inspect the organization's readiness on
[Capabilities](https://docs.gloo.com/forge/console/platform/capabilities).

## Declaration

Every connection carries a **declaration** — three facts about the API surface itself, shown as
chips on the connection card and editable from the same **Edit API** form that owns the connection's
name, base URL, and field template:

* **Kind** — `read`, `compute`, or `write`. A financial or destructive write is a `write`; there is
  no stricter kind.
* **Sends something out** — using this surface delivers content to an outside party. Calling an
  outside system in order to *read* is not this, whatever HTTP verb the read protocol happens to
  use.
* **Touches sensitive data** — the surface carries financial records or PII.

A connection with no declaration reads **Undeclared** on its card. Absent is not "declares
nothing": it is treated as the strictest case. A newly created connection starts at the strictest
declaration (`write`, sends out, sensitive), pre-selected rather than blank, so lowering it is a
deliberate act.

The seeded connections are declared in the platform fixture. The deploy seed fills in a connection
that has no declaration yet, but it does **not** overwrite one you have edited — your declaration
survives redeploys, the same way an operator-owned credential is left untouched. The trade is that
correcting a declaration in the platform fixture no longer reaches a connection that already has
one; change it in the console, or clear it first.

Editing a declaration requires the same `vendors:write` permission that already guards the rest of
the connection form.

> [!NOTE]
>
> Nothing enforces a declaration. It is stored, shown, and editable; no hold reads it against an
> agent's rung.

## Connecting a vendor through authorization-code OAuth

For a connection whose registry metadata declares authorization-code OAuth, Forge separates three
things that older credential-owned flows combined:

* The **OAuth application** is the vendor client registration: client ID, protected client-secret
  reference, environment, issuer, and rotation generation. Forge canonicalizes it by connection
  target, environment, issuer, and client ID — never by Credential scope — so the same vendor
  application is not duplicated merely because several Forge scopes use it.
* The **connected account grant** is one provider account authorized through that application,
  such as one QuickBooks company or realm.
* A **Credential binding** grants one Forge scope access to that connected account. Runtime tools,
  agents, procedures, sandboxes, and capability providers still resolve this ordinary Credential;
  they never select or receive a grant ID.

One client registration can authorize several provider accounts, and one connected account can
serve several scoped Credential bindings. Choose **Use existing account** to add a binding without
contacting the provider again. Choose **Connect new account** to start hosted consent for another
provider account. Forge never silently replaces an already connected verified account.

The Registry displays those layers separately. **Credentials** shows the ordinary Forge access
bindings and their System, Org Unit, Agent, or other scope. **Connected accounts** shows each
provider account and its authorized scopes, lifecycle, identity state, and binding count.
**OAuth applications** shows the shared vendor client registrations and how many connected accounts
each authorizes. To deployment administrators, a connected account remains visible and can be
reconnected or revoked even when it has zero Credential bindings; removing a Credential must not
strand an invisible provider grant. Target-wide connected-account and application metadata is not
exposed to organization-scoped readers.

Hosted **Connect** is the only interactive provisioning path for authorization-code OAuth.
OAuth connections do not expose the generic Advanced, Provision account, or credential-edit forms:
entering a client ID and client secret registers the vendor application, but it cannot create a
connected account without provider consent. An attempted client-registration-only provision fails
without writing a Credential and reports `oauth_connect_required`.

### Customer-owned organization scopes

Deployment administrators can choose an active **Organization Customer** wherever a new manual or
OAuth Credential binding accepts an Org Unit scope. On submit, Forge validates the Customer and
creates or reuses a distinct, parentless Customer organization; the resulting org-unit ID—not the
Customer or WorkOS ID—is the Credential owner. New Customer-owned credentials are sealed from
descendant sharing by default. Editing or reconnecting an existing Credential keeps its stored
scope and does not create another Customer organization.

This identity link does not grant membership, permission, servicing access, or project attribution.
Individual Customers cannot own credentials. A missing, inactive, wrong-tier, or conflicting link
fails closed before credential provisioning, binding, or provider consent begins.

**Reconnect** replaces one grant's authorization and affects every binding shown in its blast-radius
confirmation. **Revoke** blocks local use for every binding on that grant and separately attempts
provider-side revocation. Deleting a Credential removes only that binding; after the final binding
is removed, Forge retains the orphaned grant for 30 days before bounded cleanup.

To cleanly reset an OAuth connection, delete every **Credential binding**, revoke each **connected
account**, and then choose **Delete application**. Application deletion preserves a disabled audit
tombstone rather than erasing the registration. Reconnecting later with the same client ID replaces
the protected client secret and reactivates that tombstone before provider consent begins.

Rotating an application secret affects every grant using that client registration, so review the
displayed dependent-grant count first. Grant lifecycle reports whether Forge can vend authorization;
Credential verification reports whether a recent real request through that binding succeeded.
Neither the browser nor Help exposes client secrets, token values, or internal secret references.
Creating or rotating a vendor Credential, changing its sharing, deleting its binding, and verifying
it each record a credential lifecycle audit event without the credential value or protected secret.

During deployment, the OAuth grant backfill waits for the seeded connection metadata and fails
visibly if any eligible legacy credential cannot be migrated. The subsequent OAuth application
canonicalization consolidates duplicate scope-owned registrations only after verifying their
protected client secrets match, then repoints their grants and consent sessions. Both migrations
are bounded and idempotent. An operator may rerun them from the Convex dashboard, in order, by
invoking `migrations/backfillOAuthGrants:runFromInit` with `{}` and then
`migrations/canonicalizeOAuthApplications:runFromInit` with `{}`. Treat any returned
`oauth_backfill_*` or `oauth_application_canonicalization_*` error as an incomplete rollout rather
than success.

## Lesson trust

Each connection's **Notes** list, and the **Vendor-wide notes** panel, show the vendor's active lessons. Every lesson carries a trust badge. Hover the badge to see the evidence source that recorded it: *Live verify*, *Converged across respecs*, *Operator* or *Builder hypothesis*.

| Badge | Meaning |
| - | - |
| **Verified** | An endpoint a live call proved. It is read-only. |
| **Earned** | A pitfall or quirk recorded by an operator, a live verify, or convergence across respecs. |
| **Lead** | A pitfall or quirk a prior Builder recorded while grounding its calls. It is an unconfirmed hypothesis: confirm it before relying on it. |

The badge reads the stored `evidence.source`, using the same rule the Builder's vendor resolve uses. That resolve serves leads apart from earned knowledge, so a Builder's guess never outranks the declared documentation. Editing and deleting notes work the same for every badge. There is no action that promotes a lead to earned.

## Forward "Vendor" badge

Tool and procedure detail pages under *Platform* carry a small **Vendor** chip linking back to the vendor's registry entry — discovery lives in Platform, the trust lens lives here, and the badge stitches the two sections together.

## Key state to watch

* **Approval status** — informational in this release (no enforcement). It is the seam for a future Trust Fabric gate that would block or hold dispatch through a non-approved vendor.
* **Links** — vendors are seeded from a platform fixture and auto-linked to matching tools and procedures on deploy; operators curate links and metadata thereafter. A link whose primitive was deleted is skipped from the detail view rather than shown stale.

## How vendors get into the registry

A starter set ships in the platform fixture and is upserted on every deploy (idempotent). The seeder also auto-links existing tools and procedures whose identifier tokens match a vendor's alias keys. Everything is curatable afterward; new vendors and links can be created directly (requires the `vendors:write` permission — read access is `vendors:read`).

## Splunk

Forge treats Splunk as a first-class vendor with three independently configured connections. This
separation lets you grant only the access each workload needs and rotate one credential without
affecting the others.

Open **Platform → Vendors → Splunk**, or go directly to
`/platform/vendors/splunk`, to manage all three connections.

### Connection model

| Connection | Use in Forge | Endpoint | Authorization | Declaration |
| - | - | - | - | - |
| **API** (`splunk/api`) | Typed Splunk Platform and Enterprise Security search and notable-management tools | `https://{managementHost}:{managementPort}` (default port `8089`) | `Bearer` platform token | `write`, sensitive |
| **MCP** (`splunk/mcp`) | Governed read-only methods discovered from Splunk MCP Server | `https://{mcpHost}:{mcpPort}/services/mcp` (default port `8089`) | Separate `Bearer` MCP token | `write`, sensitive |
| **HEC** (`splunk/hec`) | Foundation credential for exporting Forge telemetry to HTTP Event Collector | `https://{hecHost}:{hecPort}/services/collector/event` (default port `443`) | `Splunk` HEC token | `write`, sends out, sensitive |

The **Declaration** column is what each connection declares about itself — see
[Declaration](https://docs.gloo.com/forge/console/platform/vendors#declaration). All three carry security telemetry keyed
to identities, and HEC exists to deliver Forge's own events outward. Nothing enforces these values
yet.

Enter host names only — the scheme and port come from the endpoint template above, so a pasted
`https://` prefix is rejected.

API and MCP share the management host (`es-<stack>.splunkcloud.com`) on port `8089`. **HEC does
not.** Splunk Cloud serves HEC from a dedicated ingest host, `http-inputs-<stack>.splunkcloud.com`,
on port `443`. Port `8088` applies to Splunk Enterprise and to Splunk Cloud free trials.

Each connection has its own credential basket and scope ladder. Forge never reuses the API token
for MCP or HEC, and it never copies a legacy token into a new credential. Choose system scope for
a shared floor or a narrower organization-unit or agent scope when tenant isolation requires it.

### Provision and verify a connection

1. On the Splunk vendor page, expand the connection you want to configure.
2. Select **Provision account**.
3. Choose the credential scope and enter the host, port, and connection-specific token.
4. Save the credential. The secret value is encrypted and is not projected back to the browser.
5. Select **Verify now** on the saved credential.
6. Confirm the verification status shown beside the credential.

The connection's declaration is edited from **Edit API** on the same connection card, not from the
provisioning form — it describes the API surface, not one credential.

Verification is intentionally safe:

* **API** authenticates against the configured management endpoint and records safe service or
  principal metadata when Splunk supplies it.
* **MCP** connects over Streamable HTTP and lists methods. Forge records method names and schema
  fingerprints, not upstream descriptions or raw schemas.
* **HEC** sends an empty-body proof with a request-channel identifier. It verifies the token
  without indexing a telemetry event.

Forge stores only bounded proof evidence such as readiness, verifier version, target host,
service version, response code, discovered method count, and catalog hash. Tokens, authorization
headers, response bodies, search queries, and raw MCP schemas are never written to verification
history.

### Govern Splunk MCP methods

After MCP verification discovers a catalog, the **MCP tool policy** card appears on the Splunk
vendor page.

1. Review each discovered method and its compact schema fingerprint.
2. Classify the method's risk.
3. Select **Approve** only for methods that are safe for agent use.
4. Select **Quarantine** for methods that should remain unavailable.
5. Assign the `splunk_mcp` tool to an agent only after the required methods are approved.

Forge binds a remote method only when the exact current method name and schema fingerprint are
approved, the method is classified `read`, and the server still advertises it. New, changed,
removed, quarantined, and non-read methods fail closed. Write operations should use typed tools,
where Trust Fabric can apply the explicit tool contract and risk classification.

Users with `vendors:read` can inspect the catalog and policy evidence. `vendors:write` is required
to approve or quarantine methods.

### Typed Splunk REST tools

Forge currently ships two connection-first Splunk Enterprise Security tools:

* `splunk_search_notables` runs an SPL search through the approved `splunk/api` credential.
* `splunk_update_notable` writes a triage disposition through that same approved connection.

At dispatch, Forge resolves the credential through the run's scope chain. If no approved,
eligible `splunk/api` credential resolves, the tool is unavailable; Forge does not fall back to a
tool-local token or base URL.

### HEC and telemetry export

The HEC connection and verification flow are available now so operators can establish and prove
the trust boundary. The platform-level `telemetry_export` capability, durable outbox, exporter,
queue controls, replay flow, and canary action are a separate follow-up and are not active in this
release. Provisioning `splunk/hec` alone does not cause Forge telemetry to leave the platform.

### Troubleshooting

| Symptom | What to check |
| - | - |
| Verification is **invalid** | Confirm the token belongs to this connection and has the required Splunk-side permissions. Do not reuse an API token for MCP or HEC. |
| Verification is **unreachable** | Confirm DNS, TLS trust, firewall/allowlist rules, host, port, and the expected Splunk service path. Forge requires HTTPS. |
| Verification **times out** after \~10s on API or MCP | Port `8089` is closed to the internet on Splunk Cloud until the caller's IP is on the search-api allow list — added via the ACS API or a Splunk Support case. A dropped SYN produces a timeout, not a refusal, so this reads as a hang rather than an error. Confirm with `curl -m 10 https://<host>:8089/services/server/info`: a timeout means the port is blocked, a `401` means it is open and the token is the problem. |
| Verification **times out** on HEC | Check the host and port. Splunk Cloud HEC is `http-inputs-<stack>.splunkcloud.com` on `443`, not the search head on `8088`. |
| MCP is authenticated but **degraded** | The server advertised zero methods. Check Splunk MCP role and tool mappings, then verify again. |
| A previously approved MCP method is unavailable | Compare its current schema fingerprint. Changed or removed methods require operator review and never retain approval by name alone. |
| A typed REST tool cannot resolve a credential | Confirm the credential target is `splunk/api`, its approval is current, it is not expired, and its scope is eligible for the run. |

### Official Splunk references

* [Splunk Cloud Platform](https://www.splunk.com/en_us/products/splunk-cloud-platform.html)
* [Splunk Enterprise](https://www.splunk.com/en_us/products/splunk-enterprise.html)
* [Splunk Cloud Platform documentation](https://help.splunk.com/en/splunk-cloud-platform)
* [Splunk Enterprise documentation](https://help.splunk.com/en/splunk-enterprise)

## Related surfaces

* [Credentials](https://docs.gloo.com/forge/console/platform/credentials.md): the credentials Forge presents to these vendors.
* [Capabilities](https://docs.gloo.com/forge/console/platform/capabilities): the capability providers a vendor backs.
* [External Apps](https://docs.gloo.com/forge/console/platform/external-apps): the inbound direction.


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