Organization Object

Organization operations are exposed by the organizations sub-api (clerkClient.organizations)

createOrganization(params)

Creates an organization.

1
const organizationID = 'my-organization-id'
2
const createdBy = 'my-user-id';
3
const organization = await clerkClient.organizations.createOrganization({organizationID, createdBy});

Available parameters are:

Name	Type	Description
name	string	Name of the organization.
slug	string
createdBy	string	The user id for the user creating the organization. The user will become an administrator for the organization.
publicMetadata	Record<string, unknown>	Metadata saved on the organization, that is visible to both your Frontend and Backend APIs.
privateMetadata	Record<string, unknown>	Metadata saved on the organization that is only visible to your Backend API.

createOrganizationInvitation(params)

Creates an invitation for new users to join an organization.

1
const name = 'my-organization-name';
2
const inviterUserId = 'my-user-id';
3
const emailAddress = 'user-email-address';
4
const role = 'role-to-assign-user';
5
const organization = await clerkClient.organizations.createOrganizationInvitation({name, inviterUserId, emailAddress, role});

Available parameters are:

Name	Type	Description
organizationID	string	The organization Id of the organization a user is being invited to.
inviterUserId	string	The user id of the user creating the invitation.
emailAddress	string	The email address to send the invitation to.
role	OrganizationMembershipRole	The role to assign the invited user within the organization.
publicMetadata	Record<string, unknown>	Metadata saved on the invitation that is visible to both your Frontend and Backend APIs.
redirectUrl	string	The URL users will land at once the organization invitation has been accepted.

createOrganizationMembership(params)

Creates membership to an organization for a user directly (circumventing the need for an invitation).

1
const organizationId = 'my-organization-id';
2
const userId = 'my-user-id';
3
const role = 'role-to-assign-user';
4
const organization = await clerkClient.organizations.createOrganizationMembership({organizationId, userId, role});

Available parameters are:

Name	Type	Description
organizationId	string	The organization Id of the organization a user is being added to.
userId	string	The user id of the user being added to the organization.
role	OrganizationMembershipRole	The role to assign the added user within the organization.

deleteOrganization(organizationId)

Deletes an organization given a valid id. Throws an error otherwise.

1
const organizationId = 'my-organization-id';
2
const organization = await clerk.organizations.deleteOrganization(organizationId);

deleteOrganizationMembership(params)

Removes a user from the specified organization.

1
const organizationId = 'my-organization-id';
2
const userId = 'my-user-id';
3
const organization = await clerkClient.organizations.deleteOrganizationMembership({organizationId, userId});

Available parameters are:

Name	Type	Description
organizationId	string	The id of the organization the user will be removed from.
userId	string	The user id to remove from the organization.

getOrganization(params)

Retrieves a single organization by the organization id, if the id is valid. Throws an error otherwise.

1
const organizationId = 'my-organization-id';
2
const organization = await clerkClient.organizations.getOrganization({
3
  organizationId
4
});

getOrganizationList(params?: GetOrganizationListParams)

Retrieves organization list:

1
const organizations = await clerkClient.organizations.getOrganizationList();

Retrieves organization list that is filtered by the number of results. More params can be found at the OrganizationListParams definition.

1
const sessions = await clerkClient.organizations.getOrganizationList({
2
  limit: 10,
3
});

getOrganizationMembershipList(params)

Retrieves organization membership list:

1
const memberships = await clerkClient.organizations.getOrganizationMembershipList();

Retrieves orgnanization membership list that is filtered by the number of results. More params can be found at the GetOrganizationMembershipListParams definition.

1
const memberships = await clerkClient.organizations.getOrganizationMembershipList({
2
  limit: 10,
3
});

getPendingOrganizationInvitationList(params)

Retrieves a list of organization invitations that have not yet been accepted.

1
const invitations = await clerkClient.organizations.getPendingOrganizationInvitationList();

Retrieves orgnanization invitation list that is filtered by the number of results. More params can be found at the GetOrganizationInvitationListParams definition.

1
const invitations = await clerkClient.organizations.getOrganizationInvitationList({
2
  limit: 10,
3
});

revokeOrganizationInvitation(params)

Revokes an organization invitation from a user for the specified organization.

1
const organizationId = 'my-organization-id';
2
const invitationId = 'my-invitation-id';
3
const requestingUserId = 'my-user-id';
4
const organization = await clerkClient.organizations.revokeOrganizationInvitation({organizationId, invitationId, requestingUserId});

Available parameters are:

Name	Type	Description
organizationId	string	The id of the organization the user was invited to.
invitationId	string	Id of the invitation to be revoked.
requestingUserId	string	Id of the user revoking the organization invitation.

updateOrganization(organizationId, params)

Updates the organization name.

1
const name = 'my-organization-name';
2
const organization = await clerkClient.organizations.updateOrganization(name);

Available parameters are:

Name	Type	Description
name	string	Updated name of the organization.

updateOrganizationMembership(params)

Updates a user's organization membership parameters.

1
const organizationId = 'my-organization-id';
2
const userId = 'my-user-id';
3
const role = 'role-to-assign-user';
4
const organization = await clerkClient.organizations.updateOrganizationMembership({organizationId, userId, role});

Available parameters are:

Name	Type	Description
organizationId	string	The organization Id of the organization a user is being added to.
userId	string	The user id of the user being added to the organization.
role	OrganizationMembershipRole	The role to assign the added user within the organization.

updateOrganizationMetadata(organizationId, params)

Updates the metadata associated with the specified organization id.

1
const update = clerkClient.organizations.updateOrganizationMetadata("id",{
2
  publicMetadata:{
3
    "example": "metadata"
4
  }
5
})

Available parameters are:

Name	Type	Description
publicMetadata	Record<string, unknown>	Metadata saved on the organization, that is visible to both your Frontend and Backend APIs.
privateMetadata	Record<string, unknown>	Metadata saved on the organization that is only visible to your Backend API.

updateOrganizationMembershipMetadata(params)

Updates the metadata associated with a user's organization membership.

1
const update = clerkClient.organizations.updateOrganizationMembershipMetadata("id",{
2
  publicMetadata:{
3
    "example": "metadata"
4
  }
5
})

Available parameters are:

Name	Type	Description
organizationId	string	The id of the organization this membership belongs to.
userId	string	The user id associated with the metadata being updated.
publicMetadata	Record<string, unknown>	Metadata saved on the organization, that is visible to both your Frontend and Backend APIs.
privateMetadata	Record<string, unknown>	Metadata saved on the organization that is only visible to your Backend API.