Skip to main content
Docs
Dashboard

Organization object

The Organization object holds information about an organization, as well as methods for managing it.

To use these methods, you must have the Organizations feature enabled in your app's settings in the Clerk Dashboard.

Properties

  • Name
    id
    Type
    string
    Description

    The unique identifier of the related organization.

  • Name
    name
    Type
    string
    Description

    The name of the related organization.

  • Name
    slug
    Type
    string | null
    Description

    The organization slug. If supplied, it must be unique for the instance.

  • Name
    imageUrl
    Type
    string
    Description

    Holds the organization logo or default logo. Compatible with Clerk's Image Optimization.

  • Name
    hasImage
    Type
    boolean
    Description

    A getter boolean to check if the organization has an uploaded image. Returns false if Clerk is displaying an avatar for the organization.

  • Name
    membersCount
    Type
    number
    Description

    The number of members the associated organization contains.

  • Name
    pendingInvitationsCount
    Type
    number
    Description

    The number of pending invitations to users to join the organization.

  • Name
    adminDeleteEnabled
    Type
    boolean
    Description

    A getter boolean to check if the admin of the organization can delete it.

  • Name
    maxAllowedMemberships
    Type
    number
    Description

    The maximum number of memberships allowed for the organization.

  • Name
    createdAt
    Type
    Date
    Description

    The date when the organization was created.

  • Name
    updatedAt
    Type
    Date
    Description

    The date when the organization was last updated.

  • Name
    publicMetadata
    Type
    OrganizationPublicMetadata
    Description

    Metadata that can be read from the Frontend API and Backend API and can be set only from the Backend API.

Methods

addMember()

Adds a user as a member to an organization. A user can only be added to an organization if they are not already a member of it and if they already exist in the same instance as the organization. Only administrators can add members to an organization.

Returns an OrganizationMembership object.

function addMember(params: AddMemberParams): Promise<OrganizationMembership>

AddMemberParams

  • Name
    userId
    Type
    string
    Description

    The ID of the user to be added as a member to the organization.

  • Name
    role
    Type
    string
    Description

    The role that the user will have in the organization.

Example

await organization.addMember({ userId: 'user_123', role: 'org:admin' })

createDomain()

Creates a new domain for the currently active organization. Returns an OrganizationDomain object.

Warning

You must have Verified domains enabled in your app's settings in the Clerk Dashboard.

function createDomain(domainName: string): Promise<OrganizationDomainResource>

Parameters

  • Name
    domainName
    Type
    string
    Description

    The domain name that will be added to the organization.

Example

await clerk.organization.createDomain('test-domain.com')

destroy()

Deletes the organization. Only administrators can delete an organization.

Deleting an organization will also delete all memberships and invitations. This is not reversible.

function destroy(): Promise<void>

Example

await clerk.organization.destroy()

getDomain()

Retrieves a domain for an organization based on the given domain ID. Returns an OrganizationDomain object.

Warning

You must have Verified domains enabled in your app's settings in the Clerk Dashboard.

function getDomain(params: GetDomainParams): Promise<OrganizationDomain>

GetDomainParams

  • Name
    domainId
    Type
    string
    Description

    The ID of the domain that will be fetched.

Example

await clerk.organization.getDomain({ domainId: 'domain_123' })

getDomains()

Retrieves the list of domains for the currently active organization. Returns a ClerkPaginatedResponse of OrganizationDomain objects.

Warning

You must have Verified domains enabled in your app's settings in the Clerk Dashboard.

function getDomains(params?: GetDomainsParams): Promise<ClerkPaginatedResponse<OrganizationDomain>>

GetDomainsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    enrollmentMode?
    Type
    'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion'
    Description

    An enrollment mode will change how new users join an organization.

Example

await clerk.organization.getDomains()

getInvitations()

Retrieves the list of invitations for the currently active organization. Returns a ClerkPaginatedResponse of OrganizationInvitation objects.

function getInvitations(
  params?: GetInvitationsParams,
): Promise<ClerkPaginatedResponse<OrganizationInvitation>>

GetInvitationsParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    status?
    Type
    'pending' | 'accepted' | 'revoked'
    Description

    The status an invitation can have.

Example

await clerk.organization.getInvitations()

getMemberships()

Retrieves the list of memberships for the currently active organization. Returns a ClerkPaginatedResponse of OrganizationMembership objects.

function getMemberships(
  params?: GetMembersParams,
): Promise<ClerkPaginatedResponse<OrganizationMembership>>

GetMembersParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    role?
    Type
    OrganizationCustomRoleKey[]
    Description

    The roles of memberships that will be included in the response.

Example

For an example on how to use getMemberships(), see the custom flow on managing organization roles.

getMembershipRequests()

Retrieve the list of membership requests for the currently active organization. Returns a ClerkPaginatedResponse of OrganizationMembershipRequest-request) objects.

Warning

You must have Organizations, and Verified domains and Automatic suggestion enabled in your app's settings in the Clerk Dashboard.

function getMembershipRequests(
  params?: GetMembershipRequestParams,
): Promise<ClerkPaginatedResponse<OrganizationMembershipRequestResource>>

GetMembershipRequestParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

  • Name
    status?
    Type
    string
    Description

    The status of the membership requests that will be included in the response.

Example

For an example on how to use getMembershipRequests(), see the custom flow guide on managing membership requests.

getRoles()

Returns a paginated list of roles in the organization. Returns a ClerkPaginatedResponse of RoleResource objects.

function getRoles(params?: GetRolesParams): Promise<ClerkPaginatedResponse<RoleResource>>

GetRolesParams

  • Name
    initialPage?
    Type
    number
    Description

    A number that can be used to skip the first n-1 pages. For example, if initialPage is set to 10, it is will skip the first 9 pages and will fetch the 10th page.

  • Name
    pageSize?
    Type
    number
    Description

    A number that indicates the maximum number of results that should be returned for a specific page.

Example

await clerk.organization.getRoles()

inviteMember()

Creates and sends an invitation to the target email address for becoming a member with the role passed on the function parameters. Returns an OrganizationInvitation object.

function inviteMember(params: InviteMemberParams): Promise<OrganizationInvitation>

InviteMemberParams

  • Name
    emailAddress
    Type
    string
    Description

    The email address to invite.

  • Name
    role
    Type
    string
    Description

    The role of the new member.

Example

await clerk.organization.inviteMember({ emailAddress: 'test@test.com', role: 'org:member' })

inviteMembers()

Creates and sends an invitation to the target email addresses for becoming a member with the role passed in the parameters. Returns an array of OrganizationInvitation objects.

function inviteMembers(params: InviteMembersParams): Promise<OrganizationInvitation[]>

InviteMembersParams

  • Name
    emailAddresses
    Type
    string[]
    Description

    The email addresses to invite.

  • Name
    role
    Type
    string
    Description

    The role of the new members.

Example

await clerk.organization.inviteMembers({
  emailAddresses: ['test@test.com', 'test2@test.com'],
  role: 'org:member',
})

removeMember()

Removes a member from the organization based on the userId. Returns an OrganizationMembership object.

function removeMember(userId: string): Promise<OrganizationMembership>

Parameters

  • Name
    userId
    Type
    string
    Description

    The ID of the user to remove from the organization.

Example

await organization.removeMember('user_123')

Sets or replaces an organization's logo. The logo must be an image and its size cannot exceed 10MB. Returns an Organization object.

function setLogo(params: SetOrganizationLogoParams): Promise<Organization>

SetOrganizationLogoParams

  • Name
    file
    Type
    File | Blob | null
    Description

    An image file or blob which cannot exceed 10MB. Passing null will delete the organization's current logo.

Example

await clerk.organization.setLogo({ file })

update()

Updates an organization's attributes. Returns an Organization object.

function update(params: UpdateOrganizationParams): Promise<Organization>

UpdateOrganizationParams

  • Name
    name
    Type
    string
    Description

    The organization name.

  • Name
    slug?
    Type
    string | undefined
    Description

    The organization slug.

  • Name
    maxAllowedMemberships?
    Type
    number | undefined
    Description

    The maximum number of memberships allowed for the organization.

  • Name
    publicMetadata?
    Type
    OrganizationPublicMetadata
    Description

    Metadata that can be read from both the Frontend API and Backend API, but can be set only from the Backend API.

  • Name
    privateMetadata?
    Type
    OrganizationPrivateMetadata
    Description

    Metadata that is only visible to your Backend API.

Example

await clerk.organization.update({ name: 'New Name' })

updateMember()

Updates a member. Currently, only a user's role can be updated. Returns an OrganizationMembership object.

function updateMember(params: UpdateMembershipParams): Promise<OrganizationMembership>

UpdateMembershipParams

  • Name
    userId
    Type
    string
    Description

    The ID of the user to update.

  • Name
    role
    Type
    string
    Description

    The role of the new member.

Example

await organization.updateMember({ userId: 'user_123', role: 'org:admin' })

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on