Create an organization
A signed-in user needs to create a workspace or tenant.
Clerk · Class
Organization
Clerk is the central interface for Clerk authentication and user management. Its organization APIs create and retrieve organizations and support choosing the active organization.
How it works
The Clerk class exposes organization operations alongside authentication and user-management capabilities. Its organization methods can create an organization for the current user, retrieve one by identifier, and use an organization resource or identifier when setting the active organization.
Syntax
createOrganization(params: CreateOrganizationParams): Promise<OrganizationResource>
getOrganization(organizationId: string): Promise<OrganizationResource>Parameters
| Name | Type | Description |
|---|---|---|
params | CreateOrganizationParams | Creation options, including the organization's name and optional slug. |
organizationId | string | The identifier of the organization to retrieve. |
Returns
createOrganization(params: CreateOrganizationParams): Promise<OrganizationResource>; getOrganization(organizationId: string): Promise<OrganizationResource>.
Key points
- Clerk is the main interface for authentication and user-management functionality.
- The class also centralizes access to users, sessions, API keys, billing, and organizations.
- Its organization-related state can expose the last active organization membership.
- Creating an organization programmatically makes the current user an administrator.
- The creation method receives CreateOrganizationParams and resolves to an OrganizationResource.
- The retrieval method looks up one organization by its ID.
Common mistakes
- Passing null for the organization when setting the active session removes the current organization from the active context.
Example: Create an organization
import { createClerkClient } from '@clerk/backend';
const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY });
const organization = await clerk.organizations.createOrganization({
name: 'Acme Inc.',
slug: 'acme-inc',
});
console.log(organization.id);Creates an organization with a name and slug, then prints its identifier.
When to use it
Retrieve organization data
An application needs organization details from a known identifier.
Set the active organization
A user switches between organizations in a multi-tenant application.
Interview questions
QWhat organization capabilities does the Clerk class provide?
The class provides organization-related operations as part of Clerk's central application interface. It supports creating an organization, retrieving one by ID, and selecting the active organization.
Follow-up: How would you clear the active organization? Pass null for the organization parameter when calling the active-session method.
QWhat does createOrganization return and what side effect does it have?
createOrganization accepts CreateOrganizationParams and returns a Promise<OrganizationResource>. Creating an organization also adds the current user as an administrator.
Follow-up: What should a caller retain after creation? The returned OrganizationResource, including its identifier, can be used for subsequent organization operations.
QHow do you retrieve an organization?
getOrganization takes an organization ID as a string and returns a Promise<OrganizationResource>. It is used to retrieve one specific organization.
Follow-up: Can the active organization be selected using more than an object? Yes; the active-organization parameter can use an organization resource or an organization ID/slug string.
Related
CreateOrganizationParamsOrganizationResourceSetActiveParamsSession.user.organizationMembershipsOrganizationProfileCreateOrganization