Organization
object
The Organization
object holds information about an organization, as well as methods for managing it.
The following examples assume:
- you have followed the quickstart in order to add Clerk to your JavaScript application
- you have enabled the Organizations feature in your Clerk Dashboard
Properties
Name | Type | Description |
---|---|---|
id | string | The unique identifier of the related organization. |
name | string | The name of the related organization. |
slug | string | null | The organization slug. If supplied, it must be unique for the instance. |
logoUrl (deprecated) | string | null | Deprecated in favor of imageUrl . |
imageUrl | string | Holds the organization logo or default logo. Compatible with Clerk's Image Optimization. |
hasImage | boolean | A getter boolean to check if the organization has an uploaded image. Returns false if Clerk is displaying an avatar for the organization. |
membersCount | number | The number of members the associated organization contains. |
pendingInvitationsCount | number | The number of pending invitations to users to join the organization. |
adminDeleteEnabled | boolean | A getter boolean to check if the admin of the organization can delete it. |
maxAllowedMemberships | number | The maximum number of memberships allowed for the organization. |
createdAt | Date | Date of the time the organization was created. |
updatedAt | Date | Date of the last time the user was updated. |
publicMetadata | object | Additional 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
Name | Type | Description |
---|---|---|
name | string | The organization name. |
slug? | string | undefined | The organization slug. |
update()
returns
Type | Description |
---|---|
Promise<Organization> | This method returns a Promise which resolves to an Organization object. |
update()
example
main.jsimport 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
Type | Description |
---|---|
Promise<void> | This method returns a Promise which doesn't resolve to any value. |
destroy()
example
main.jsimport 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>
setLogo()
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
Name | Type | Description |
---|---|---|
file | File | Blob | null | An image file or blob which cannot exceed 10MB. Passing null will delete the organization's current logo. |
setLogo()
returns
Type | Description |
---|---|
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.jsimport 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); }
index.html<div id="app"></div> <input type="file" id="org-logo" /> <button id="upload-logo">Upload Logo</button> <!-- 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){ // 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); } }); </script>
getRoles()
Returns a paginated list of roles in the organization.
function getRoles: (params?: GetRolesParams) => Promise<ClerkPaginatedResponse<RoleResource>>;
GetRolesParams
Name | Type | Description |
---|---|---|
initialPage? | number | 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. |
pageSize? | number | A number that indicates the maximum number of results that should be returned for a specific page. |
getRoles()
returns
Type | Description |
---|---|
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.
Name | Type | Description |
---|---|---|
id | string | The unique identifier of the role. |
key | string | The unique key of the role. |
name | string | The name of the role. |
description | string | The description of the role. |
permissions | PermissionResource[] | The permissions of the role. |
createdAt | string | The date and time the role was created. |
updatedAt | string | The date and time the role was last updated. |
PermissionResource
An experimental interface that includes information about a user's permission.
Name | Type | Description |
---|---|---|
id | string | The unique identifier of the role. |
key | string | The unique key of the role. |
name | string | The name of the role. |
type | 'system' | 'user' | The type of the permission. |
createdAt | string | The date and time the role was created. |
updatedAt | string | The date and time the role was last updated. |
getRoles()
example
main.jsimport 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