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

> The External App API — endpoints called by external apps to manage their own agents and customers and discover available models. Distinct from the management API and the inference carve-out.

Last updated 2026-11-11

·
applies to 2026-09-30

·
main

Forge exposes three distinct HTTP surfaces for external integrations. Understanding which surface you're talking to matters because they use different URL prefixes, different auth semantics, and different response envelopes:

| Surface | Prefix | Who calls it | Response envelope |
| - | - | - | - |
| **Management API** | `/api/v3/*` (and `/api/v2/*`, the compatibility surface) | Operators, CI/CD, backend services | `{ data, meta }` Forge envelope |
| **Inference carve-out** | `/api/inference/v1/*` | Third-party LLM SDKs, AI agents | OpenAI-compatible |
| **External App endpoints** | `/api/v3/me/customers*`, `/api/v3/agents/find-or-create`, `/api/v3/agent-available-models` (v2: `/api/v2/external/*`) | External apps on behalf of their users | Mixed (see each endpoint) |

This section documents the **External App endpoints** of the HTTP API. In v3 its operations live under `/api/v3/me/customers`, `/api/v3/agents/find-or-create` and `/api/v3/agent-available-models`; the v2 compatibility surface serves the same operations under `/api/v2/external/*`. These endpoints are called by your external application using an external-app bearer token to manage the agents and model access it has provisioned for its users. They are **not** for managing external app registrations themselves (that's `/api/v3/external-apps/*`) and are **not** for sending chat completions (that's `/api/inference/v1/chat/completions`).

***

## Authentication

All External App endpoints, at their v3 and their v2 paths, require an **external-app bearer token** — the same credential you use for inference requests. This is a JWT issued by `POST /api/inference/v1/oauth/token` using your application's `client_id` and `client_secret`.

```http theme={null}
Authorization: Bearer <your-external-app-jwt>
```

> [!WARNING]
>
> Sending your App's `client_secret` here **instead of** the JWT still works today, but that shortcut is deprecated and stops authenticating on **1 December 2026**. Responses to those requests carry `Deprecation` and `Sunset` headers — see [the companion key is not a bearer token](https://docs.gloo.com/forge/reference/http-api/externalApps#the-companion-key-is-not-a-bearer-token).

The `principalExternalApplicationId` (the Forge-internal ID of your registered external application) is always derived **server-side** from the bearer token. It is never accepted from the request body or query string. This means every resource created or accessed through these endpoints is automatically scoped to the calling application — cross-application access is structurally impossible.

### Required permissions

Each endpoint requires a catalog permission, held through your application's role grants and not narrowed away by your token's scopes:

| Endpoint | Permission | Scope that narrows to it |
| - | - | - |
| `POST /api/v3/agents/find-or-create` | `agents:write` | `agents:write` |
| `GET /api/v3/agent-available-models` | `agents:read` | `agents:read` |
| `POST /api/v3/me/customers`, `POST /api/v3/me/customers/find-or-create`, `DELETE /api/v3/me/customers/{customerId}`, `PATCH /api/v3/me/customers/{customerId}` | `customers:manage` | `customers:manage` |
| `GET /api/v3/me/customers`, `GET /api/v3/me/customers/{customerId}` | `customers:read` | `customers:read` |

Roles are given to your application in the Forge Console. If it lacks the permission, the endpoint returns `403 Forbidden` with the permission in `error.requiredPermission`.

***

## Endpoints

### Personal agent management

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/v3/agents/find-or-create` | Idempotently provision a PERSONAL agent for a user |
| `GET` | `/api/v3/agent-available-models` | Return the OpenAI-compatible model list for a specific agent |

### Customers

| Method | Path | Description |
| - | - | - |
| `POST` | `/api/v3/me/customers` | Find or create a customer by `workosId`, link it to your app, and return `201` `{customer}` |
| `POST` | `/api/v3/me/customers/find-or-create` | The same, returning `200` `{customer, created, linked}` |
| `GET` | `/api/v3/me/customers` | One page of the customers linked to your app: `{customers, count}`, optional `status`, `limit` 1-500 (default 100) and `cursor`; see [Listing customers](#listing-customers) |
| `GET` | `/api/v3/me/customers/{customerId}` | Get one linked customer: `{customer}` |
| `PATCH` | `/api/v3/me/customers/{customerId}` | Change the supplied fields of a linked customer: `{customer}` |
| `DELETE` | `/api/v3/me/customers/{customerId}` | Remove your app's own link to a customer: no body, returns `{id, unlinked: true}`; see [Removing your app's link](#removing-your-app’s-link) |

***

## Personal agents and user identity

The External App endpoints are designed around the **Personal Agent** model: every user of your application can have a dedicated Forge agent scoped to the `(your-app, user)` pair. Personal agents are provisioned on first use and reused on subsequent calls — the `findOrCreateAgent` endpoint is idempotent.

User identity flows through the `X-Forge-User-JWT` header. If your application issues JWTs for its users (the same JWTs used for inference), pass the current user's JWT on each call. Forge JIT-provisions the Forge user record if needed and associates the personal agent with that user. If you have already provisioned the user through a prior JWT-authenticated call, you can pass their Forge `userId` directly in the request body instead.

User provisioning is JWT-first

The `X-Forge-User-JWT` path is authoritative. The explicit `userId` body parameter is for callers that have already provisioned users via JWT and cached the resulting Forge user ID. If you pass an explicit `userId` for a user that has never been seen by Forge, the endpoint returns `404 Not Found` rather than provisioning them. Use the JWT path for first-time provisioning.

***

## Customers

A customer belongs to your app when a link (`customerScopes`, scope `external_app`) connects them; `create` and `findOrCreate` add that link. Customers are **shared canonical rows** deduplicated by `workosId`: when two apps register the same `workosId`, both are linked to one row and read and write the same fields, including `externalIds` and `metadata`. Do not assume per-application isolation of those fields.

Every response carries an explicit `ExternalCustomer`: `id`, `customerType` (`org` or `user`), `name`, `status` (`active`, `inactive` or `archived`), `createdAt`, `updatedAt`, and `workosId`, `primaryEmail`, `primaryPhone`, `website`, `externalIds` and `metadata` when set. The row's creator (`createdBy`) is not returned.

Not linked is not found

`GET` and `PATCH /api/v3/me/customers/{customerId}` answer `404` `resource_missing` "Customer not found" both for an id that does not exist and for a customer that exists but is not linked to your app. They used to answer `403` "Customer does not belong to this application" for the second case, which told a caller the customer existed. Only the lookup by id is closed this way: an app that knows a customer's `workosId` can still `findOrCreate` it and be linked to the existing row.

These routes accept only an External App credential. A platform API key or a Personal key gets `403` "This endpoint requires an external-application credential". With a management JWT, an `Idempotency-Key` repeat of a completed write returns the stored response only while your app is still linked to that customer; otherwise it answers `409` `idempotency_result_unavailable` and does not run again (see [External App customer writes](https://docs.gloo.com/forge/reference/idempotency.md#external-app-customer-writes)). The deprecated companion key is never idempotency-scoped. The [Forge MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#reaching-any-other-operation) reaches the same six operations through `forge_call_operation`, in the `customers` tool group. For the organization's whole customer directory, whatever app a customer is linked to, use the [Customers API](https://docs.gloo.com/forge/reference/http-api/customers).

### Listing customers

`GET /api/v3/me/customers` pages through your app's links, oldest link first. Each request reads at most `limit` links (1-500, default 100) and returns their customers, so its cost does not grow with the number of customers your app is linked to. Follow `meta.nextCursor`, passed back as `cursor`, while `meta.hasMore` is `true`:

```bash theme={null}
curl "$FORGE_BASE/api/v3/me/customers?status=active&limit=100" \
  -H "Authorization: Bearer <your-external-app-jwt>"
# { "data": { "customers": [ ... ], "count": 100 },
#   "meta": { "hasMore": true, "nextCursor": "eyJ0Ijo...", "requestId": "..." } }

curl "$FORGE_BASE/api/v3/me/customers?status=active&limit=100&cursor=eyJ0Ijo..." \
  -H "Authorization: Bearer <your-external-app-jwt>"
```

* `status` filters the customers a page's links name, after the links are read. A page can therefore hold fewer customers than `limit`, or none, while `meta.hasMore` is still `true`. Do not stop on a short page.
* A walk whose last page was exactly full ends with one empty page and `meta.hasMore: false`.
* `count` is the number of customers on this page.
* The cursor is opaque: it names a position, never a customer or link id. A cursor that does not decode, or a second `cursor` parameter, is `400` `bad_request`.

### Shared status and archive

Because a customer is one shared row, a status change is shared too. When any linked app sends `PATCH {"status": "archived"}`, every app linked to that customer, and Console, sees it archived. An archived customer stays in the list unless `status` excludes it. To restore it, send `PATCH {"status": "active"}`. Archiving an organization customer never removes its organization home in Forge, so projects homed there keep their authority; restoring it to `active` re-ensures that same home. No customer response carries that organization's org-unit id.

### Removing your app's link

`DELETE /api/v3/me/customers/{customerId}`, with no body, removes only your app's link to that customer and returns `{"id": "<customer id>", "unlinked": true}`. It is the operation Forge's own customer administration (`removeCustomerScope`) performs for an `external_app` link, under the same permission, confined to your own app.

* It never archives, deletes or changes the shared customer, never touches another app's link or any other link, and never touches the customer's organization home.
* A customer that does not exist, or one your app is not linked to (including after an earlier unlink), is `404` `resource_missing` "Customer not found". A request body carrying any other field is `400` `bad_request`.
* Afterwards your app can no longer read, update, cost-query (`GET /api/v3/customers/{customerId}/cost`) or dispatch workflows for that customer. `POST /api/v3/me/customers/find-or-create` with its `workosId` links it again, to the same shared row.
* With a management JWT, an `Idempotency-Key` repeat of a completed unlink returns the recorded acknowledgement (see [External App customer writes](https://docs.gloo.com/forge/reference/idempotency.md#external-app-customer-writes)).

***

## See also

* [External Apps](https://docs.gloo.com/forge/console/platform/external-apps) — register your application and give it roles
* [Inference Carve-Out](https://docs.gloo.com/forge/reference/inference.md) — the OpenAI-compatible completions surface
* [External Apps management API](https://docs.gloo.com/forge/reference/http-api/externalApps) — manage the external app registration itself
* [Talk to Agents](https://docs.gloo.com/forge/build/talk-to-agents.md) — the Personal Agent model from the console perspective


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