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

> OAuth2 client management for integrating systems: explicit ExternalApp responses and one-time secrets that are never stored.

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](https://docs.gloo.com/forge/reference/http-api/governance/giveRole.md); the scopes on its tokens only narrow them. See [Permissions and scopes](https://docs.gloo.com/forge/reference/conventions.md#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](https://docs.gloo.com/forge/reference/http-api/governance/giveRole.md) and [revokeRole](https://docs.gloo.com/forge/reference/http-api/governance/revokeRole.md), 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:

| Field | Type |
| - | - |
| `_id`, `ownerId`, `name`, `clientId`, `createdBy` | string |
| `legacyId`, `defaultAgentId`, `clientSecretPrefix` | string or `null` |
| `ownerType` | `user`, `factory`, `project` or `org_unit` |
| `status` | `active` or `deactivated` |
| `tokenTtlSeconds`, `createdAt` | number |
| `monthlyTokenBudget`, `perUserDailyTokenCap`, `deactivatedAt` | number or `null` |
| `budgetEnforcementMode` | `block`, `warn` or `null` |
| `allowAllAgents`, `allowAllModels` | boolean (`allowAllModels` is `false` when never set) |
| `allowedAgentIds`, `trustedWorkosApplicationIds` | string array |
| `allowedScopes` (`get`, `update` only) | string array, computed and read-only |

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](https://docs.gloo.com/forge/reference/idempotency.md#routes-that-return-a-one-time-secret) replay. A repeat with the same key and body answers the original status with only the app's `data.id` ([id-only replay](https://docs.gloo.com/forge/reference/idempotency.md#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](https://docs.gloo.com/forge/reference/http-api/externalApps) — list External Apps in the org
* `GET /api/v3/external-apps/{externalAppId}` — [getExternalApp](https://docs.gloo.com/forge/reference/http-api/externalApps) — fetch a single App by ID

Writes:

* `POST /api/v3/external-apps` — [createExternalApp](https://docs.gloo.com/forge/reference/http-api/externalApps) — provision a new App; response includes one-time `client_secret`
* `PATCH /api/v3/external-apps/{externalAppId}` — [updateExternalApp](https://docs.gloo.com/forge/reference/http-api/externalApps) — partial update (name, owner, budgets, trusted WorkOS apps)
* `POST /api/v3/external-apps/{externalAppId}/rotate-secret` — [rotateExternalAppSecret](https://docs.gloo.com/forge/reference/http-api/externalApps) — issue a new `client_secret`; response includes it once
* `POST /api/v3/external-apps/{externalAppId}/rotate-callback-secret` — [rotateExternalAppCallbackSecret](https://docs.gloo.com/forge/reference/http-api/externalApps/rotateCallbackSecret.md) — issue a new **callback signing secret**; response includes it once
* `DELETE /api/v3/external-apps/{externalAppId}` — [deactivateExternalApp](https://docs.gloo.com/forge/reference/http-api/externalApps) — 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.

| Secret | Direction | What it does |
| - | - | - |
| `client_secret` | App → Forge | Exchanged at `POST /oauth/token` for a short-lived Forge JWT. Rotate via `rotateSecret`. |
| Callback signing secret | Forge → App | Signs [workflow dispatch callbacks](https://docs.gloo.com/forge/reference/http-api/workflows#dispatch-callbacks) with `X-Forge-Signature-V2` so your receiver can verify them. Minted lazily on first callback use. Rotate via `rotateCallbackSecret`. |

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

> [!WARNING]
>
> **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](https://docs.gloo.com/forge/reference/conventions.md#deprecation-signalling):

```http theme={null}
Deprecation: @1787184000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
```

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:

| What you send | Status |
| - | - |
| A three-segment JWT (`eyJ...` with two dots) from `POST /oauth/token` | Supported — no action needed |
| The `client_secret` string you captured from `create` / `rotateSecret` | **Deprecated** — migrate before the sunset date |

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:

```bash theme={null}
# 1. Exchange the client_secret you already hold for a short-lived JWT.
FORGE_TOKEN=$(curl -s -X POST "$FORGE_BASE/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$FORGE_CLIENT_ID" \
  -d "client_secret=$FORGE_CLIENT_SECRET" \
  | jq -r .access_token)

# 2. Call the Platform API with the JWT — not with the client_secret.
curl -s "$FORGE_BASE/api/v3/agents" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

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](https://docs.gloo.com/forge/reference/conventions.md#requesting-scopes-at-token-mint).

## Common workflows

Provision a new App and capture the secret:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/external-apps" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage GitHub Action",
    "ownerType": "org_unit",
    "ownerId": "ou_abc"
  }'
```

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](https://docs.gloo.com/forge/reference/http-api/governance/giveRole.md)) 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.

> [!WARNING]
>
> `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:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/external-apps/app_abc/rotate-secret" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

Rotate the callback signing secret — update your receiver **before** running this, since there is no overlap window:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/external-apps/app_abc/rotate-callback-secret" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

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

## Related

* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token
* [Quickstart](https://docs.gloo.com/forge/quickstart.md) — first calls over HTTP


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