Retrieve an organization
Load a known organization before displaying its details or using its organization methods.
Clerk · Interface
OrganizationResource
OrganizationResource is Clerk’s client-side object type for an organization. It is returned by organization retrieval and creation methods and can be used as the active-organization value.
How it works
OrganizationResource is the client-side Organization object returned by Clerk when an organization is fetched or created. It represents an organization resource that can also be supplied when setting the active organization.
Syntax
function getOrganization(organizationId: string): Promise<OrganizationResource>
function createOrganization(params: CreateOrganizationParams): Promise<OrganizationResource>Parameters
| Name | Type | Description |
|---|---|---|
organizationId | string | Identifier of the organization to retrieve. |
params | CreateOrganizationParams | Creation options for the organization. |
Returns
OrganizationResource for organization retrieval or creation.
Key points
- getOrganization retrieves one organization by its identifier and returns it asynchronously as an OrganizationResource.
- createOrganization creates an organization and resolves to an OrganizationResource.
- The Clerk organization property provides a shortcut to the last active organization membership.
- An active organization can be represented by the resource itself or by its ID or slug string.
Common mistakes
- The active organization shortcut can be absent when there is no authenticated session.
- Passing null while setting the active organization clears the current selection.
Example: Read the active organization
import { clerk } from '@clerk/...?'
const organization = clerk.organization
if (organization) {
console.log(organization.id)
}Reads the currently active organization resource when one is available.
When to use it
Provision a tenant
Create a tenant for a newly onboarded customer and retain the returned organization resource.
Set the active organization
Select the current tenant using an already loaded resource rather than another lookup.
Interview questions
QWhat does OrganizationResource represent?
OrganizationResource is the object type returned for a Clerk organization resource. Clerk exposes it through organization-related APIs such as getOrganization and createOrganization.
Follow-up: How can an active organization be cleared? Pass null as the organization value when calling the client’s active-session setter.
QWhat does getOrganization return?
getOrganization accepts an organization identifier and resolves to a Promise of OrganizationResource. The result is the organization object that the client can use for organization operations.
Follow-up: What input forms can be used when setting an active organization? The documented value may be null, an organization ID or slug string, or an OrganizationResource object.
QWhen might the organization value be absent?
The Clerk organization shortcut is tied to the last active organization membership on the session user. It can therefore be undefined or null when no usable session organization exists.
Follow-up: What is the difference between clearing and selecting? Clearing uses null; selecting can use an ID, slug, or resource object.
Related
OrganizationCreateOrganizationParamsgetOrganizationcreateOrganizationsetActiveorganizationMemberships