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

# Customers

> Read and manage the organization's customer directory over the Platform API.

The Customers API is the organization's whole customer directory: every customer, organizations (`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`](https://docs.gloo.com/forge/reference/http-api/external#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](https://docs.gloo.com/forge/reference/http-api/customers/list.md) — the whole directory, oldest first, with `status` and `customerType` filters and cursor paging, up to 100 rows per page
* [Get customer](https://docs.gloo.com/forge/reference/http-api/customers/get.md) — one customer by id
* [List customer scopes](https://docs.gloo.com/forge/reference/http-api/customers/listScopes.md) — the org units, External Applications, projects and factories a customer is linked to, up to 100; `meta.partial` reports more

## Write operations

* [Create customer](https://docs.gloo.com/forge/reference/http-api/customers/create.md) — an organization or individual, provisioned in WorkOS as the Console does unless you pass an existing `workosId`
* [Update customer](https://docs.gloo.com/forge/reference/http-api/customers/update.md) — name, type, status, contact fields, `externalIds` or `metadata`
* [Archive customer](https://docs.gloo.com/forge/reference/http-api/customers/archive.md) — status `archived`; restore with Update customer and `status: "active"`

Every write accepts an optional `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](https://docs.gloo.com/forge/reference/idempotency.md#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`](https://docs.gloo.com/forge/reference/http-api/external#customers) instead of Create customer. The [Forge MCP server](https://docs.gloo.com/forge/reference/mcp-server.md#reaching-any-other-operation) reaches these six operations through `forge_call_operation`, in the `customers` tool group.


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