org) and individuals (user), whichever External Applications it is linked to. It is what the Console’s customer pages show and change. Reads use the customers:read scope and require that permission at the deployment root. Writes use the customers:manage scope together with customers:read, because every write answers the customer it wrote, and require both permissions at the deployment root, the same permissions and home the Console’s customer pages use. A grant held only below the deployment root receives 403 permission_denied naming the missing permission.
Any Platform API credential can hold that authority: a Personal key acts with its owner’s grants narrowed by its scopes, a platform API key with its own role grants, and an External Application with a role grant that holds the permission there: one a person gave it, or a legacy compatibility grant mapped from the app’s earlier scopes. An External Application’s own app-linked view stays at /api/v3/me/customers; the routes here never consult those links.
Every response carries an explicit Customer: id, customerType, name, status (active, inactive or archived), createdAt, updatedAt, and workosId, primaryEmail, primaryPhone, website, externalIds and metadata when set. The row’s creator is never returned. A missing or malformed customer id is 404 resource_missing “Customer not found”.
Operations
- List customers — the whole directory, oldest first, with
statusandcustomerTypefilters and cursor paging, up to 100 rows per page - Get customer — one customer by id
- List customer scopes — the org units, External Applications, projects and factories a customer is linked to, up to 100;
meta.partialreports more
Write operations
- Create customer — an organization or individual, provisioned in WorkOS as the Console does unless you pass an existing
workosId - Update customer — name, type, status, contact fields,
externalIdsormetadata - Archive customer — status
archived; restore with Update customer andstatus: "active"
Idempotency-Key; send one with every create. A same-key retry within 24 hours returns the recorded 201 (create) or 200 only while the credential’s scopes still reach customers:read and its grants still hold customers:read and customers:manage at the deployment root; otherwise 409 idempotency_result_unavailable, and the write never runs twice (see Customer directory writes). A customer row is shared: a change here is seen by every application linked to it and by the Console.
An External Application that wants a customer linked to itself uses findOrCreate instead of Create customer. The Forge MCP server reaches these six operations through forge_call_operation, in the customers tool group.
