Skip to main content
POST
Create an organization for the signed-in user

Authorizations

Authorization
string
header
required

WorkOS access JWT or a user-owned WorkOS API key. User keys are bound to one organization and restricted to their enabled product permissions. Session-only onboarding and session revocation require an interactive access JWT. No cookie session is assumed.

Headers

X-Request-Id
string

Optional caller-provided correlation identifier.

Required string length: 1 - 128
Idempotency-Key
string
required

Stable creator-scoped key; repeat unchanged to observe an incomplete creation.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9._:-]+$

Body

application/json
name
string
required
Required string length: 1 - 128
Pattern: ^\S(?:.*\S)?$
signup_source
string

Optional public acquisition source from a link's r parameter; never a secret or an access code. Omit it when the customer arrived directly. A workspace referral value (ref-...) or a flag value (flag-..., while that project still shows the flag) gives the user's first workspace 1,000 credits and 30 days of granted Paid access; other promotional credits are server-configured. Direct signup and invalid referral values create a Free workspace without a referral reward. Attribution is fixed for the user, and rewards are never multiplied by retries or additional organizations.

Required string length: 1 - 64
Pattern: ^[a-z0-9][a-z0-9_-]{0,63}$

Response

Organization and Owner membership are persisted. Idempotent replay returns the same identity.

id
string
required
Pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
name
string
required
Required string length: 1 - 128