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 whenownerType 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.
listreturns only the apps you may manage, up to 100 per page, continued withmeta.nextCursor.get,update,deactivate,rotateSecretandrotateCallbackSecretanswer404 resource_missingfor an app you may not manage, exactly like a missing one.create, and anupdatethat changesownerType/ownerId, needapps:manageat the new owner’s home too; otherwise they answer403 permission_deniedwithrequiredPermission: "apps:manage".- An External App can never change its own owner (
403).
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 areactive 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 orgGET /api/v3/external-apps/{externalAppId}— getExternalApp — fetch a single App by ID
POST /api/v3/external-apps— createExternalApp — provision a new App; response includes one-timeclient_secretPATCH /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 newclient_secret; response includes it oncePOST /api/v3/external-apps/{externalAppId}/rotate-callback-secret— rotateExternalAppCallbackSecret — issue a new callback signing secret; response includes it onceDELETE /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 yourclient_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.
Every request that still takes the shortcut is answered with the deprecation headers:
Am I affected?
Look at the token you put in theAuthorization 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: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: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.
Rotate when a secret is compromised:
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 with403, even when it holds the permission.
- List the agents an External App owns, newest first, with
apps:readat platform scope. Pass the app’sid. 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 holdsagents: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.
apps:read at platform scope, else 403. It writes nothing.
Related
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token - Quickstart — first calls over HTTP

