Create a customer organization
Provisioning a tenant during onboarding
Clerk · Module
organizations.createOrganization
Creates a Clerk Organization through the backend SDK. Provide a name and optionally a creator, slug, membership limit, and metadata.
How it works
Call the backend organization's createOrganization method with the required name and optional creator, slug, membership limit, and metadata fields. It returns a promise resolving to the newly created Organization; the creator, when supplied, becomes an administrator.
Syntax
function createOrganization(params: CreateParams): Promise<Organization>Parameters
| Name | Type | Description |
|---|---|---|
name | string | The name of the Organization. |
createdBy? | string | The ID of the user creating the Organization; that user becomes an admin. |
maxAllowedMemberships? | number | Maximum memberships allowed; 0 means unlimited. |
privateMetadata? | OrganizationPrivateMetadata | Metadata readable and writable only through the Backend API. |
publicMetadata? | OrganizationPublicMetadata | Metadata readable through frontend and backend APIs, but writable only through the Backend API. |
slug? | string | The organization's slug. |
Returns
Promise<Organization>
Key points
- The method provisions a new Clerk Organization.
- Use maxAllowedMemberships to impose a ceiling on organization memberships.
- name identifies the organization and is the required CreateParams field.
- slug lets the caller provide the organization's slug.
- privateMetadata is intended for backend-only organization data.
- publicMetadata can be read by both frontend and backend API clients.
- The SDK delegates organization creation to Clerk's backend API endpoint.
Common mistakes
- Setting maxAllowedMemberships to 0 removes the membership cap rather than preventing memberships.
- If createdBy is supplied, that user is assigned an administrator role in the new organization.
- Private and public metadata have backend-only write restrictions, so do not treat either field as freely writable from frontend code.
Example: Create an organization with an admin
const name = 'test-org'
const createdBy = 'user_123'
const organization = await clerkClient.organizations.createOrganization({ name, createdBy })
console.log(organization.id)Creates an organization through the backend Clerk client and logs the returned organization ID.
When to use it
Assign the creator as admin
Associating an initial administrator
Store organization metadata
Attaching server-controlled organization attributes
Limit memberships
Controlling organization size
Interview questions
QWhat does organizations.createOrganization return?
It is a backend SDK method with the signature createOrganization(params: CreateParams): Promise<Organization>. The required parameter is name; the result is a promise for the created Organization.
Follow-up: How would you make the creator an administrator? Pass the creator's user ID in createdBy; the documentation states that this user becomes an admin.
QWhat is the purpose of createdBy?
createdBy is an optional user ID identifying who creates the organization. That user becomes an administrator of the resulting organization.
Follow-up: What happens if no creator is supplied? The method can still create the organization, but no creator-based administrator assignment is specified by this page.
QHow do metadata and membership limits differ?
The method accepts optional privateMetadata and publicMetadata. Private metadata is readable and settable only through the Backend API, while public metadata can be read through frontend and backend APIs but set only through the Backend API.
Follow-up: How can membership capacity be configured? Supply maxAllowedMemberships; a value of 0 means unlimited memberships.
Related
CreateParamsOrganizationclerkClientPOST /organizations