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 byPOST /api/inference/v1/oauth/token using your application’s client_id and client_secret.
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:
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
Customers
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.
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.
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). The deprecated companion key is never idempotency-scoped. The Forge MCP server 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.
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:
statusfilters the customers a page’s links name, after the links are read. A page can therefore hold fewer customers thanlimit, or none, whilemeta.hasMoreis stilltrue. Do not stop on a short page.- A walk whose last page was exactly full ends with one empty page and
meta.hasMore: false. countis 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
cursorparameter, is400bad_request.
Shared status and archive
Because a customer is one shared row, a status change is shared too. When any linked app sendsPATCH {"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
404resource_missing“Customer not found”. A request body carrying any other field is400bad_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-createwith itsworkosIdlinks it again, to the same shared row. - With a management JWT, an
Idempotency-Keyrepeat of a completed unlink returns the recorded acknowledgement (see External App customer writes).
See also
- External Apps — register your application and give it roles
- Inference Carve-Out — the OpenAI-compatible completions surface
- External Apps management API — manage the external app registration itself
- Talk to Agents — the Personal Agent model from the console perspective

