Skip to main content
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. 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.
An External App outlives the people who set it up; a Personal key 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.
“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.
  • 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). 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.
None of these share a schema or a console page with External Apps.
External Apps (dark)External Apps (light)

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 for the full scope-to-permission catalog.
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.
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. 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 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. 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.
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.
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).
  • 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.
  • Webhooks (/platform/webhooks) — outbound webhook configuration for platform events: targets, signing secrets and event filters. Full operator guide: Webhooks.

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 (/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: