Create customer
Creates a customer exactly as the Console does. Requires permission customers:manage.
name and customerType (org or user), and optionally primaryEmail, primaryPhone, website, externalIds, metadata and workosId. The body is strict: an unknown field or an empty string is 400 bad_request.
Without workosId, Forge first provisions the customer in WorkOS: a WorkOS organization for org, or a WorkOS user for user, created with primaryEmail (or a Forge placeholder address when none is given). It then records the customer; if recording fails, the WorkOS entity it provisioned is deleted. With workosId, Forge provisions nothing: a customer already recorded with that WorkOS id is returned unchanged with created: false, and otherwise a new customer is recorded with it. An active organization customer gets its organization home, as in the Console.
An unexpected failure, such as WorkOS being unavailable while an organization is provisioned, is 500 internal_error; every directory route declares it.
The credential needs both the customers:read and customers:manage scopes, and customers:read and customers:manage granted at the deployment root; otherwise 403 permission_denied names the missing permission and nothing is provisioned.
Success is 201 with {customer, created}. Send an Idempotency-Key: a same-key retry within 24 hours returns the recorded 201 and provisions nothing, while the caller still holds both permissions at the deployment root; a recorded refusal or failure, or a caller that lost that authority, gets 409 idempotency_result_unavailable, and nothing runs again. A retry without a key runs again and, without workosId, provisions another WorkOS identity. When a request’s outcome is unknown, repeat it with the same key first (409 idempotency_key_in_flight while the first attempt is still running). Only after Forge answers idempotency_outcome_unknown or idempotency_result_unavailable, check List customers and use a new key if the customer was not created.Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255
