Skip to main content
External Apps are first-class OAuth2 clients — the credentials integrating systems use to call the Forge Platform API. Each App carries an ownerType + ownerId (the org unit it acts on behalf of) and a client_secret used to mint short-lived bearer tokens at the OAuth2 token endpoint. What an App may do is its role grants, given by a holder of grants:manage in the Forge Console or with giveRole; the scopes on its tokens only narrow them. See Permissions and scopes. Every External App route (/api/v3/external-apps/*, and /api/v2/externalApps/* at v2), including list and get, requires apps:manage, and the credential’s scopes must reach apps:manage. Grant changes are separate and require grants:manage. The Console’s Convex list and get functions use apps:read. The External Apps domain exists so that a key or App holding apps:manage can provision and rotate credentials for downstream integrations programmatically.

Who can manage an app

Every External App has a management home: its owning org unit when ownerType is org_unit, otherwise (a user, factory or project owner, or an org unit that no longer exists) the deployment root org unit. A key or App may act on an app only while it holds apps:manage at that home, an org unit above it, the deployment root org unit, or the platform scope.
  • list returns only the apps you may manage, up to 100 per page, continued with meta.nextCursor.
  • get, update, deactivate, rotateSecret and rotateCallbackSecret answer 404 resource_missing for an app you may not manage, exactly like a missing one.
  • create, and an update that changes ownerType/ownerId, need apps:manage at the new owner’s home too; otherwise they answer 403 permission_denied with requiredPermission: "apps:manage".
  • An External App can never change its own owner (403).
A credential granted at the root org unit or the platform scope manages every app. An App holding apps:manage only at a partner organization’s root manages only the apps owned in that partner’s tree. Role grants are not written through these routes: give or revoke an App’s roles in the Forge Console or with giveRole and revokeRole, which require grants:manage.

Resource shape

list returns ExternalApp objects; get and update return ExternalAppDetail, which adds allowedScopes. Both are explicit allowlists built field by field: Every field is always present; a value that was never set is null. The encrypted callback signing secret and any stored field not listed here are never returned.

Secrets are never stored

create, rotateSecret and rotateCallbackSecret return a secret exactly once. Forge keeps only a salted hash of the client secret and an encrypted copy of the callback signing secret, and it never stores these responses for Idempotency-Key replay. A repeat with the same key and body answers the original status with only the app’s data.id (id-only replay), without the secret, and does not run again. If a create’s outcome is unknown, repeat it with the same key to learn the app’s id, then rotate its secret.

Lifecycle

External Apps are active by default. Deactivation is a soft-delete: the App row is marked inactive and any resources owned by it are archived. The Phase 2 deactivation cascade covers all app-private resources: agents (archived), skills (archived), workflows (retired), memory (the channel memory of the app’s agents hard-deleted; the app’s long-term memory soft-deleted as FORGOTTEN), knowledge entries (deleted: content removed from search, record kept as an audited tombstone; this includes the cases the app’s agents recorded, wherever they wrote them), and files (hard-deleted). Other resources without a principalExternalApplicationId — shared project corpora, human-uploaded files — are never touched. The client_secret is shown once on createExternalApp and once on rotateExternalAppSecret — the platform never re-displays a secret after that response. Lose it, and you must rotate.

Operations

Reads:
  • GET /api/v3/external-apps — listExternalApps — list External Apps in the org
  • GET /api/v3/external-apps/{externalAppId} — getExternalApp — fetch a single App by ID
Writes:
  • POST /api/v3/external-apps — createExternalApp — provision a new App; response includes one-time client_secret
  • PATCH /api/v3/external-apps/{externalAppId} — updateExternalApp — partial update (name, owner, budgets, trusted WorkOS apps)
  • POST /api/v3/external-apps/{externalAppId}/rotate-secret — rotateExternalAppSecret — issue a new client_secret; response includes it once
  • POST /api/v3/external-apps/{externalAppId}/rotate-callback-secret — rotateExternalAppCallbackSecret — issue a new callback signing secret; response includes it once
  • DELETE /api/v3/external-apps/{externalAppId} — deactivateExternalApp — soft-delete the App and archive its agents

Two secrets, two jobs

An App can hold two independent keys. Rotating one does not touch the other.

The companion key is not a bearer token

Behind every App, Forge stores one long-lived API key row. It has exactly one supported job: it is the value your client_secret is compared against when you call POST /oauth/token. The token endpoint hashes what you sent, matches it, and hands back a short-lived JWT. That JWT is what /api/v3/* and /api/v2/* expect in Authorization: Bearer. Historically the platform also accepted the companion key itself as a bearer token on /api/v2/*, skipping the token exchange entirely. That shortcut is deprecated and will be removed.
Sunset: 1 December 2026. After that date, presenting an External App’s companion API key directly as a bearer token on /api/v2/* stops authenticating and the request returns 401. Exchanging that same secret at POST /oauth/token is unaffected and remains the supported flow — you are not being asked to rotate or replace any credential, only to stop skipping the exchange.
Every request that still takes the shortcut is answered with the deprecation headers:
Nothing else about those responses changes until the sunset date — same status, same envelope, same payload.

Am I affected?

Look at the token you put in the Authorization header: If you are unsure, send a request and check the response headers. A Sunset header means you are on the deprecated path.

Migrating

Add one exchange step in front of your existing calls, and reuse the resulting token until it expires rather than minting one per request:
The example omits the scope parameter, which mints a token carrying every published app scope, so the token narrows nothing and the App’s role grants decide. Pass scope to request a narrower token; a token can never do more than the App’s roles allow. See Requesting scopes at token mint.

Common workflows

Provision a new App and capture the secret:
The client_secret in the response is shown exactly once. Store it in your CI’s secret manager immediately. The new App holds no roles, so its tokens can do nothing yet — not even inference. Give it roles on its page in the Forge Console (Platform → Developers → External Apps → the app → Roles), or with POST /api/v3/governance-holders/{holderId}/roles (giveRole) with the create response’s data.id as holderId and actorKind: "external_app". Both require grants:manage. An App may be given any role, including one that approves or administers, but only by someone who holds every permission in it, and never by the App itself.
allowedScopes is read-only. create and update refuse it with 400 and code allowed_scopes_removed — on update, an empty list included. On get and GET /api/v3/me it is computed: the catalog permissions the App’s role grants hold, sorted. It is not a grant. list omits it; read one App with get to see it.
Rotate when a secret is compromised:
Rotate the callback signing secret — update your receiver before running this, since there is no overlap window:

Owned agents (platform API key)

This admin route runs the Console’s own owned-agents list (an External App’s detail page) for a platform API key. An External App is refused with 403, even when it holds the permission.
  • List the agents an External App owns, newest first, with apps:read at platform scope. Pass the app’s id. An agent answers its id, slug, name, description, status and creation and update times. The list answers only agents the key may read: each must have a home org unit where the key also holds agents:read, and the app’s users’ Personal Agents are left out, as on every agent route. The Console lists them all. When the key’s access to an agent cannot be decided, the request fails rather than answer a shorter list. An app that owns no agents, or an id no app has, answers an empty list.
It is a platform operation: the key needs apps:read at platform scope, else 403. It writes nothing.