Inspect membership context
Display which organization a signed-in member belongs to and the member's current role.
Clerk · Class
OrganizationMembership
OrganizationMembership represents a user's membership in an Organization. It provides membership data and methods to update the member's role or remove the membership.
How it works
An OrganizationMembership represents one user's relationship with an Organization. It exposes identifying and descriptive data, the related organization and public user information, metadata, timestamps, and methods to change the member's role or delete the membership.
Syntax
function update(updateParams: UpdateOrganizationMembershipParams): Promise<OrganizationMembership>
function destroy(): Promise<OrganizationMembership>Parameters
| Name | Type | Description |
|---|---|---|
role | string | The role to assign to the member. |
Returns
The update() and destroy() methods return Promise<OrganizationMembership>; the object properties expose membership data.
Key points
- It is the SDK model for an organization's membership relationship.
- The relationship connects a user with an organization.
- id is the unique identifier for the membership.
- organization gives access to the membership's Organization.
- role records the current user's role in that organization.
- publicMetadata is readable through both the Frontend API and Backend API.
- updatedAt records when the membership most recently changed.
Common mistakes
- destroy() removes the membership from its associated organization; it does not merely deactivate the member.
Example: Manage an organization membership
const membership = session.user.organizationMemberships[0];
if (membership) {
console.log(membership.organization.name, membership.role);
await membership.update({ role: "org:admin" });
await membership.destroy();
}Reads a membership, changes its role, and then removes it from its organization. Use only when the signed-in user and application permissions allow these operations.
When to use it
Update a role
Change a member's assigned role when membership administration requires it.
Delete a membership
Remove a user from the organization.
Interview questions
QWhat does OrganizationMembership represent?
OrganizationMembership models the relationship between a user and an Organization. It includes the membership ID, associated Organization, public user data, role, public metadata, and creation and update timestamps.
Follow-up: How would you identify the organization and member represented by an instance? Use organization for the organization and publicUserData for public information about the user; id identifies the membership itself.
QHow do you change a member's role?
Call update() with an UpdateOrganizationMembershipParams object. The documented parameter is role, which supplies the new role, and the method resolves to the updated OrganizationMembership.
Follow-up: What does the update operation change? It changes the member's Role rather than replacing the membership object or organization.
QHow do you remove an organization membership?
Call destroy() on the membership. It returns a Promise<OrganizationMembership> and deletes that membership from the Organization to which it belongs.
Follow-up: What should be verified before calling it? Verify that removing this membership is intended, because the documented operation deletes the membership from its organization.
Related
OrganizationOrganizationMembershipPublicMetadataPublicUserDataUpdateOrganizationMembershipParams