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

# External Apps

> Register and govern inbound OAuth2 clients: their roles and scopes, budgets, trusted WorkOS applications, webhook subscriptions, secret rotation and what deactivation turns off.

**External Apps** (`/platform/external-apps`) is the registry of **inbound** OAuth2 clients. An External App is a partner application that exchanges a `client_id` + `client_secret` at `POST /oauth/token` for a short-lived Forge JWT, then calls the OpenAI-compatible inference surface (`/api/inference/v1/*`) and/or the Forge Platform API (`/api/v3/*`, or the `/api/v2/*` compatibility surface).

External Apps is the first tab of **Developers**, the sidebar entry labeled "Developers" that opens
`/platform/external-apps`. Developers groups the pages where you operate Forge as a developer:
External Apps, Personal keys, Forge MCP and Webhooks. Organization administration (feature flags,
members, identity, chat, email, fiscal calendars and secrets) stays under
[Settings](https://docs.gloo.com/forge/console/platform/settings).

An External App is not just an API key. It is a **first-class principal** — the tenant boundary that keys Trust Fabric governance, per-app and per-end-user budgets, agent/memory/knowledge isolation, cost attribution, and webhook subscriptions. Everything an app does is attributable to it, and deactivating it cascades.

> [!TIP]
>
> An External App outlives the people who set it up; a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md) ends with its person. In both, scopes only narrow: an app's own roles, or a Personal key owner's permissions. To pick between them, see [Choose a credential](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential).

> [!WARNING]
>
> "External App" means only the **inbound** direction — someone else's software calling Forge. Three other primitives are easy to confuse with it, and all three are **outbound** (Forge calling someone else's software):
>
> * A vendor Forge calls **out** to (Linear, 1Password, GitHub) is a capability provider plus a Virtual Key — see [Connect an External Service](https://docs.gloo.com/forge/build/set-up-external-app.md).
> * For an authorization-code vendor, that outbound credential is an **OAuth application** plus a **connected account** and a **credential binding**, managed under Platform -> Vendors — see [Vendors (operator guide)](https://docs.gloo.com/forge/console/platform/vendors). Note the near-collision: an "OAuth application" there is a credential *Forge presents to a vendor*, the opposite of an External App.
> * A Slack workspace connection is a separate primitive again — see [Slack](https://docs.gloo.com/forge/run/slack.md).
>
> None of these share a schema or a console page with External Apps.

![External Apps (light)](https://mintcdn.com/gloo-b243725a/xyq5perq6SLByPBn/forge/images/console/platform/external-apps-light.png?fit=max\&auto=format\&n=xyq5perq6SLByPBn\&q=85\&s=3b1282d248fb26f39725ffedcb682147)

External Apps — Forge Console at `/platform/external-apps`

## What you can do

* **Register an app** — name it, pick its owner scope (user / factory / project / org unit) and set budgets. The `client_secret` is shown **exactly once** on create. A new app holds no roles.
* **Give and revoke roles** — an app's authority is its role grants, managed on its **Overview** tab with `grants:manage` (see below).
* **Set budgets** — a monthly token ceiling for the app and a daily token cap per end user, with a `block` or `warn` enforcement posture.
* **List trusted WorkOS applications** — the Applications whose user JWTs this app may present for token exchange, so a partner can act as a specific end user.
* **Restrict agent access** — allow every agent in scope, or an explicit `allowedAgentIds` allowlist, with an optional default agent.
* **Manage webhooks** per app, on the app's own **Webhooks** tab: create, edit, send a test delivery, rotate the signing secret, revoke.
* **Read the delivery log** for that app's subscriptions on the **Delivery Log** tab.
* **Rotate the client secret** — mints a new secret and revokes the old one, shown once.
* **Rotate the callback signing secret** — a *different* key, used to sign workflow dispatch callbacks. See below.
* **Deactivate the app** — a soft status change plus a purge cascade (see below).

## Registering an app

**1. Create the app**

Name it and choose the **owner** — a user, factory, project, or org unit. The owner is not decoration: tier-5 of the credential resolver walks the owner's scope chain, so ownership determines which credentials the app's dispatches can reach.

**2. Capture the client secret**

The `client_secret` appears once, on the create result. Copy it into the partner's secret store before dismissing the dialog. Forge stores only a salted SHA-256 hash on a companion API-key row — it cannot recover the plaintext. If it is lost, use **Rotate secret**.

**3. Give the app the minimum roles**

Default-deny: a new app holds no roles, so it can mint a token but every route rejects it. Open the app, and under **Roles** choose **Manage roles**. Give a role holding `inference:use` for the inference surface, and only roles carrying the permissions the integration actually calls.

**4. Set a budget before going live**

An app with no `monthlyTokenBudget` is uncapped. Set the ceiling and the per-user daily cap, and choose `block` (reject at the cap with HTTP 429) over `warn` for anything customer-facing.

**5. Verify the token flow**

Have the partner mint a token and make one real call. A `403` names the missing permission in `error.requiredPermission`: either the app's roles lack it, or the token did not ask for the scope that narrows to it. A 401 with `wrong_scope` from the inference surface means the token was minted without `inference:app`.

## Roles and scopes

An External App is an **actor**, like a person: what it may do is the **role grants** it holds. Roles are given and revoked on the app's **Overview** tab, in the **Roles** card, by someone holding `grants:manage`; without `grants:read` the card shows nothing. Give a role at platform scope, or at the organization the app's requests act in. For an app owned by an org unit, that is the top organization of the owner's chain, and **Manage roles** labels it. A role given only at an organization below it never reaches the app's requests, so the dialog does not offer one. An app owned by a user, factory or project acts at the deployment root: give its roles at platform scope.

A **scope** grants nothing. The scopes a token asks for at `POST /oauth/token` only narrow what the app's roles allow. See [Permissions and scopes](https://docs.gloo.com/forge/reference/conventions.md#permissions-and-scopes) for the full scope-to-permission catalog.

> [!WARNING]
>
> An app can be given any role, including one that approves or administers (`approvals:approve`, `grants:manage`). Only someone who holds every permission in the role can give it, and nobody can give a role to themselves. Give an approve or administer role only to an app you trust with that authority: anyone holding the app's secret can use it.

Below the Roles card, the **Overview** tab shows what the app's roles let it do, split into inference access and management permissions. This is the app's `allowedScopes` as the API returns it: the catalog permissions its role grants hold, computed, read-only, and not a grant. Each permission reads as its label, in words, and a set that is exactly a preset (such as **Governance reader**: `grants:read`, `policies:read` and `audit:read`) is shown by the preset's name. **Technical details** gives the **Token scope**: `inference:app` when the app has inference access, then those catalog permissions, space-separated, ready to send as a token request's `scope` value. The create and edit forms no longer offer a scope picker, and the API refuses a write of `allowedScopes` with `allowed_scopes_removed`.

> [!NOTE]
>
> Each active app that held scopes before roles decided authority was given a compatibility role, `compat_external_app:<id>`, holding exactly the permissions their old scopes mapped to (minus any never-held permission). It shows under **Roles** and can be revoked, but not given again.

## Webhooks (per app)

The app detail page's **Webhooks** tab manages that app's subscriptions. App-scoped delivery is **initiator-only**: an app receives events for the runs it started, never anyone else's.

| Affordance | Notes |
| - | - |
| Create | HTTPS URL + at least one event. The signing secret is shown once. |
| Edit | Change URL, label, events, or delivery format. |
| Send test | Queues a synthetic `webhook.test` delivery through the full signing + retry pipeline. Check the **Delivery Log** tab for the result. |
| Rotate secret | Mints a new signing secret, shown once. In-flight deliveries already signed are not re-signed. |
| Revoke | Permanent. The row is retained for audit; create a new subscription to resume delivery. |

App-scoped subscriptions may carry only the five initiator-attributable events (`approval.requested`, `approval.sla_breached`, `approval.resolved`, `workflow.started`, `workflow.completed`) — and no `*` wildcard, because a wildcard would promise more than initiator-only delivery can honor. Admin-owned subscriptions on [Platform → Webhooks](https://docs.gloo.com/forge/run/webhooks.md) carry the full platform event registry plus `*`.

Destination URLs are validated on create **and** update: HTTPS only, no CR/LF, no embedded credentials, and no loopback / link-local / private / cloud-metadata hosts.

**Replay** is admin-only today; use Platform → Webhooks for it.

## Key state to watch

* **Status** — `active` or `deactivated`. A deactivated app's tokens are rejected and it cannot mint new ones.
* **Client secret prefix** — the first characters of the live secret. Use it to confirm which secret a partner is holding without revealing it.
* **Consecutive failures** on each webhook subscription. At 10 the subscription auto-pauses and an `event.delivery.failed` notification fires. Recurring auto-pauses mean the downstream is unhealthy — page its owner rather than resuming on a loop.
* **Budget burn** against `monthlyTokenBudget`. In `warn` mode an exceeded budget records a platform event and lets the call through; in `block` mode the call gets HTTP 429.
* **Trusted WorkOS applications** — validated on write to live in the same WorkOS environment as Forge, so a cross-account Application cannot be added.
* **MCP server status** (Forge MCP tab) — when it is off, every incoming MCP connection is refused.
* **Webhook delivery health** (Webhooks tab) — each configured target shows its recent delivery success rate.

## Rotating the client secret

Rotate mints a new secret, returns it once, and revokes the previous one. There is no overlap window: the old secret stops working when the new one is issued, so coordinate the cutover with the partner. Rotate is rejected with `409` on a deactivated app — reactivating by rotation is not a supported path; re-create the app instead.

## Callback signing secret

An app has a **second, independent key**: the callback signing secret. Rotating one has no effect on the other, and confusing them is the most common support ticket on this surface.

| Key | Direction | Purpose |
| - | - | - |
| **Client secret** | Partner → Forge | Exchanged at `POST /oauth/token` for a short-lived Forge JWT. Proves the caller is the app. |
| **Callback signing secret** | Forge → Partner | Signs [workflow dispatch callbacks](https://docs.gloo.com/forge/reference/http-api/workflows#dispatch-callbacks) with `X-Forge-Signature-V2`. Lets the partner's receiver prove the POST came from Forge. |

A dispatch callback is what a partner gets when it passes `callback: { url }` to `POST /api/v3/workflows/dispatch`: exactly one signed POST when the run reaches a terminal state, carrying the v2 event envelope. Only External App callers may ask for one — there is no key to sign with otherwise, and Forge refuses to deliver a callback unsigned.

* The secret is **minted lazily**, on the app's first callback. An app that has never used a callback has no callback secret, and that is not a misconfiguration.
* It is shown **once**, on rotate. Forge stores only an encrypted form.
* **Rotation is immediate and total** — no overlap window. Update the partner's receiver *before* rotating, or verification fails on the next delivery.
* Rotate is rejected with `409` on a deactivated app, same posture as the client secret.

> [!WARNING]
>
> The signing key is resolved **per attempt**, not per delivery. A delivery already mid-retry-chain when you rotate will have its remaining attempts signed with the *new* key — so a receiver that has not been updated rejects the retries too, and the delivery dead-letters. Update the receiver first.

## Deactivation cascade

Deactivating is a soft status change plus a purge cascade. It is not a delete: the row, its audit trail, and its cost attribution survive.

> [!WARNING]
>
> The cascade archives or deletes app-owned resources. It is not a dry run and there is no one-click undo.

On deactivate the platform:

1. Marks the app `deactivated` and stamps `deactivatedAt`.
2. Revokes the companion API-key row, so token minting stops immediately.
3. Schedules seven purge jobs, each scoped to this app: **agents** (archived), **skills** (archived through the version FSM), **workflows** (retired), **channel memory** (deleted), **long-term memory** (marked forgotten), **knowledge entries** (deleted: the entries the app added and the cases its agents recorded or last rewrote), and **files** (blob + row deleted for files the app uploaded).

Purge jobs are idempotent and batched, so a partially-run cascade is safe to re-trigger by deactivating again.

## The Developers tabs

The tabs run from what calls in to what goes out. Each keeps its own URL.

* **External Apps** (`/platform/external-apps`) — the registry of inbound OAuth2 clients: software that must keep working after the person who set it up leaves. This page.
* **Personal keys** (`/platform/personal-keys`) — every person's Personal keys and MCP host sign-ins, with revoke, for administrators. Shown to people who hold `apikeys:read`. Full operator guide: [Personal keys (all people)](https://docs.gloo.com/forge/console/platform/personal-keys.md).
* **Forge MCP** (`/platform/forge-mcp`) — one page with three sections: **Status** turns the MCP server on or off and shows the endpoint hosts connect to; **Access** turns tool groups on or off, explains listing jobs, and holds the Global Instructions every session is sent; **What agents see** lists each listing job's tools and their size. Forge MCP holds no credentials of its own. Full operator guide: [Forge MCP](https://docs.gloo.com/forge/console/platform/forge-mcp.md).
* **Webhooks** (`/platform/webhooks`) — outbound webhook configuration for platform events: targets, signing secrets and event filters. Full operator guide: [Webhooks](https://docs.gloo.com/forge/console/platform/webhooks.md).

## Your own connection

Connecting your own AI host is a personal task, so it lives in your own settings, not here:

* **Settings → Connect an agent** (`/settings/connect-agent`) — the endpoint and the setup for each supported host, sign-in first.
* [Settings → Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md) (`/settings/personal-keys`) — your own keys and host sign-ins, and the scopes each one has.

## Moved pages

These URLs redirect, so stored links and bookmarks keep working:

| Old URL | Redirects to |
| - | - |
| `/platform/forge-mcp/configuration` | `/platform/forge-mcp` |
| `/platform/forge-mcp/connect` | `/settings/connect-agent` |
| `/platform/forge-mcp/api-keys` | `/settings/personal-keys` |

## Related surfaces

* [Personal keys](https://docs.gloo.com/forge/console/settings/personal-keys.md) — a person's own key, and [how to choose between the two](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential)
* [Webhooks (operator guide)](https://docs.gloo.com/forge/run/webhooks.md) — signature verification, retries, the failure budget, retention
* [External Apps HTTP API](https://docs.gloo.com/forge/reference/http-api/externalApps) — programmatic registration and rotation
* [Workflows HTTP API — dispatch callbacks](https://docs.gloo.com/forge/reference/http-api/workflows#dispatch-callbacks) — what the callback signing secret signs, and receiver-side verification
* [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md) — the inbound counterpart for senders that cannot hold a credential
* [Webhooks HTTP API](https://docs.gloo.com/forge/reference/http-api/webhooks) — the app's own self-service subscription management
* [Inference carve-out](https://docs.gloo.com/forge/reference/inference.md) — the OpenAI-compatible surface these apps call
* [Trust Fabric in production](https://docs.gloo.com/forge/run/trust-fabric.md) — the gates every app dispatch passes
* [Budgets and cost](https://docs.gloo.com/forge/run/budgets-and-cost.md) — how per-app ceilings are enforced and attributed
* [Connect an External Service](https://docs.gloo.com/forge/build/set-up-external-app.md) — the OUTBOUND primitive this page is often confused with


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