Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

Organization object

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

The following examples assume:

Properties

NameTypeDescription
idstringThe unique identifier of the related organization.
namestringThe name of the related organization.
slugstring | nullThe organization slug. If supplied, it must be unique for the instance.
logoUrl (deprecated)string | nullDeprecated in favor of imageUrl.
imageUrlstringHolds the organization logo or default logo. Compatible with Clerk's Image Optimization.
hasImagebooleanA getter boolean to check if the organization has an uploaded image. Returns false if Clerk is displaying an avatar for the organization.
membersCountnumberThe number of members the associated organization contains.
pendingInvitationsCountnumberThe number of pending invitations to users to join the organization.
adminDeleteEnabledbooleanA getter boolean to check if the admin of the organization can delete it.
maxAllowedMembershipsnumberThe maximum number of memberships allowed for the organization.
createdAtDateDate of the time the organization was created.
updatedAtDateDate of the last time the user was updated.
publicMetadataobjectAdditional information about the organization that can be read through the Frontend API, but written only from the Backend API.

Methods

update()

Updates an organization's attributes.

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

UpdateOrganizationParams

NameTypeDescription
namestringThe organization name.
slug?string | undefinedThe organization slug.

update() returns

TypeDescription
Promise<Organization>This method returns a Promise which resolves to an Organization object.

update() example

main.js
import Clerk from '@clerk/clerk-js'; // Initialize Clerk with your Clerk publishable key const clerk = new Clerk('{{pub_key}}'); await clerk.load(); if (clerk.user) { // Check for an active organization if (clerk.organization){ await clerk.organization.update({ name: "New Name" }) .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); clerk.mountSignIn(signInDiv); }
index.html
<div id="app"></div> <!-- Initialize Clerk with your Clerk Publishable key and Frontend API URL --> <script async crossorigin="anonymous" data-clerk-publishable-key="{{pub_key}}" src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js" type="text/javascript" ></script> <script> window.addEventListener("load", async function () { await Clerk.load(); if (Clerk.user) { // Check for an active organization if (Clerk.organization){ await Clerk.organization.update({ name: "New Name" }) .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); Clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); Clerk.mountSignIn(signInDiv); } }); </script>

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>;

destroy() returns

TypeDescription
Promise<void>This method returns a Promise which doesn't resolve to any value.

destroy() example

main.js
import Clerk from '@clerk/clerk-js'; // Initialize Clerk with your Clerk publishable key const clerk = new Clerk('{{pub_key}}'); await clerk.load(); if (clerk.user) { // Check for an active organization if (clerk.organization){ await clerk.organization.destroy() .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); clerk.mountSignIn(signInDiv); }
index.html
<div id="app"></div> <!-- Initialize Clerk with your Clerk Publishable key and Frontend API URL --> <script async crossorigin="anonymous" data-clerk-publishable-key="{{pub_key}}" src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js" type="text/javascript" ></script> <script> window.addEventListener("load", async function () { await Clerk.load(); if (Clerk.user) { // Check for an active organization if (Clerk.organization){ await Clerk.organization.destroy() .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); Clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); Clerk.mountSignIn(signInDiv); } }); </script>

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

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

SetOrganizationLogoParams

NameTypeDescription
fileFile | Blob | nullAn image file or blob which cannot exceed 10MB. Passing null will delete the organization's current logo.

setLogo() returns

TypeDescription
Promise<Organization>This method returns a Promise which resolves to an Organization object.

setLogo() example

For the following example, your HTML file should look like this:

index.html
<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <link rel="icon" type="image/svg+xml" href="/vite.svg" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Clerk + JavaScript App</title> </head> <body> <div id="app"></div> <input type="file" id="org-logo" /> <button id="upload-logo">Upload Logo</button> <script type="module" src="/main.js"></script> </body> </html>

And your JavaScript file should look like this:

main.js
import Clerk from '@clerk/clerk-js'; // Initialize Clerk with your Clerk publishable key const clerk = new Clerk('{{pub_key}}'); await clerk.load(); if (clerk.user) { // Check for an active organization if (clerk.organization){ // Update the organization's logo document.getElementById("upload-logo").addEventListener("click", () => { const orgLogo = document.getElementById("org-logo").files[0]; clerk.organization.setLogo({ file: orgLogo }) .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); }); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); clerk.mountSignIn(signInDiv); }

getRoles()

Returns a paginated list of roles in the organization.

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

GetRolesParams

NameTypeDescription
initialPage?numberA 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.
pageSize?numberA number that indicates the maximum number of results that should be returned for a specific page.

getRoles() returns

TypeDescription
Promise<ClerkPaginatedResponse<RoleResource>>This method returns a Promise which resolves to a ClerkPaginatedResponse of RoleResource objects.

RoleResource

An experimental interface that includes information about a user's role.

NameTypeDescription
idstringThe unique identifier of the role.
keystringThe unique key of the role.
namestringThe name of the role.
descriptionstringThe description of the role.
permissionsPermissionResource[]The permissions of the role.
createdAtstringThe date and time the role was created.
updatedAtstringThe date and time the role was last updated.

PermissionResource

An experimental interface that includes information about a user's permission.

NameTypeDescription
idstringThe unique identifier of the role.
keystringThe unique key of the role.
namestringThe name of the role.
type'system' | 'user'The type of the permission.
createdAtstringThe date and time the role was created.
updatedAtstringThe date and time the role was last updated.

getRoles() example

main.js
import Clerk from '@clerk/clerk-js'; // Initialize Clerk with your Clerk publishable key const clerk = new Clerk('{{pub_key}}'); await clerk.load(); if (clerk.user) { // Check for an active organization if (clerk.organization) { await clerk.organization.getRoles() .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); }else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); clerk.mountSignIn(signInDiv); }
index.html
<div id="app"></div> <!-- Initialize Clerk with your Clerk Publishable key and Frontend API URL --> <script async crossorigin="anonymous" data-clerk-publishable-key="{{pub_key}}" src="https://{{fapi_url}}/npm/@clerk/clerk-js@latest/dist/clerk.browser.js" type="text/javascript" ></script> <script> window.addEventListener("load", async function () { await Clerk.load(); if (Clerk.user) { // Check for an active organization if (Clerk.organization) { await Clerk.organization.getRoles() .then((res) => console.log(res)) .catch((error) => console.log("An error occurred:", error.errors)); } else { // If there is no active organization, // mount Clerk's <OrganizationSwitcher /> // to allow the user to set an organization as active document.getElementById("app").innerHTML = ` <h2>Select an organization to set it as active</h2> <div id="org-switcher"></div> `; const orgSwitcherDiv = document.getElementById("org-switcher"); Clerk.mountOrganizationSwitcher(orgSwitcherDiv); } } else { document.getElementById("app").innerHTML = ` <div id="sign-in"></div> `; const signInDiv = document.getElementById("sign-in"); Clerk.mountSignIn(signInDiv); } }); </script>

Additional methods

In addition to the methods listed on this page, the Organization object also has the following methods:

Members

Invitations

Domains

Last updated on March 26, 2024

What did you think of this content?

Clerk © 2024