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
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
Date of the time the organization was created.
- Name
updatedAt
- Type
Date
- Description
Date of the last time the organization was updated.
- Name
publicMetadata
- Type
object
- Description
Additional information about the organization that can be read through the Frontend API, but written only from the Backend API.
function update(params: UpdateOrganizationParams): Promise<Organization>;
- Name
name
- Type
string
- Description
The organization name.
- Name
slug?
- Type
string | undefined
- Description
The organization slug.
Returns
Type | Description |
---|---|
Promise<Organization> | This method returns a Promise which resolves to an Organization object. |
Example
import { Clerk } from '@clerk/clerk-js';
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_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);
}
<div id="app"></div>
<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
async
crossorigin="anonymous"
data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
src="https://YOUR_FRONTEND_API_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>;
Returns
Type | Description |
---|---|
Promise<void> | This method returns a Promise which doesn't resolve to any value. |
Example
import { Clerk } from '@clerk/clerk-js';
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_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);
}
<div id="app"></div>
<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
async
crossorigin="anonymous"
data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
src="https://YOUR_FRONTEND_API_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>;
- 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.
Returns
Type | Description |
---|---|
Promise<Organization> | This method returns a Promise which resolves to an Organization object. |
Example
For the following example, your HTML file should look like this:
<!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:
import { Clerk } from '@clerk/clerk-js';
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_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);
}
<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="YOUR_PUBLISHABLE_KEY"
src="https://YOUR_FRONTEND_API_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>>;
- 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.
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
id
- Type
string
- Description
The unique identifier of the role.
- Name
key
- Type
string
- Description
The unique key of the role.
- Name
name
- Type
string
- Description
The name of the role.
- Name
description
- Type
string
- Description
The description of the role.
- Name
permissions
- Type
PermissionResource[]
- Description
The permissions of the role.
- Name
createdAt
- Type
string
- Description
The date and time the role was created.
- Name
updatedAt
- Type
string
- Description
The date and time the role was last updated.
PermissionResource
An experimental interface that includes information about a user's permission.
- Name
id
- Type
string
- Description
The unique identifier of the role.
- Name
key
- Type
string
- Description
The unique key of the role.
- Name
name
- Type
string
- Description
The name of the role.
- Name
type
- Type
'system' | 'user'
- Description
The type of the permission.
- Name
createdAt
- Type
string
- Description
The date and time the role was created.
- Name
updatedAt
- Type
string
- Description
The date and time the role was last updated.
import { Clerk } from '@clerk/clerk-js';
// Initialize Clerk with your Clerk publishable key
const clerk = new Clerk('YOUR_PUBLISHABLE_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);
}
<div id="app"></div>
<!-- Initialize Clerk with your
Clerk Publishable key and Frontend API URL -->
<script
async
crossorigin="anonymous"
data-clerk-publishable-key="YOUR_PUBLISHABLE_KEY"
src="https://YOUR_FRONTEND_API_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: