Skip to main content

​
Organizations API

The organizations module exposes programmatic access to Wacht’s multi-tenancy models. It allows B2B applications to create independent organizations and manage the users (members) within them. 
import { WachtClient } from "@wacht/backend";

const client = new WachtClient({ apiKey: process.env.WACHT_API_KEY });

​
Reading Organizations

​
listOrganizations()

Retrieves a paginated list of all organizations. 
const response = await client.organizations.listOrganizations({ limit: 100 });
console.log(response.data);
​
options
ListOrganizationsOptions

​
getOrganization(organizationId)

Retrieves a single organization by its ID. 
const org = await client.organizations.getOrganization("org_abc123");
​
organizationId
string
required
The unique ID of the organization to retrieve.

​
Mutating Organizations

​
createOrganization(request)

Programmatically provision a new organization. 
const newOrg = await client.organizations.createOrganization({
  name: "Acme Corp",
  slug: "acme-corp",
  created_by: "usr_xyz789" // The founder's ID
});
​
request
CreateOrganizationRequest
required

​
updateOrganization(organizationId, request)

Modify an organization’s profile, including metadata. 
const updatedOrg = await client.organizations.updateOrganization("org_abc123", {
  name: "Acme Corporation Global",
  public_metadata: { tier: "enterprise" }
});
​
organizationId
string
required
The unique ID of the organization.
​
request
UpdateOrganizationRequest
required

​
deleteOrganization(organizationId)

Permanently deletes an organization and all of its associated memberships and roles. 
await client.organizations.deleteOrganization("org_abc123");
​
organizationId
string
required
The unique ID of the organization.

​
Memberships

Organizations are collections of Users. You can assign users to an organization by adding them as members and granting them specific roles.

​
listOrganizationMembers(organizationId)

Get all users actively belonging to the organization. 
const members = await client.organizations.listOrganizationMembers("org_abc123");
​
organizationId
string
required
The target organization’s ID.

​
addOrganizationMember(organizationId, request)

Force-add a user into an organization, bypassing the standard invitation mechanisms. 
const membership = await client.organizations.addOrganizationMember("org_abc123", {
  user_id: "usr_xyz789",
  role: "org:admin"
});
​
organizationId
string
required
The ID of the organization.
​
request
AddOrganizationMemberRequest
required

​
updateOrganizationMember(organizationId, memberId, request)

Change a member’s role within the organization. 
await client.organizations.updateOrganizationMember("org_abc123", "mem_123", {
  role: "org:member"
});
​
organizationId
string
required
The exact organization ID.
​
memberId
string
required
The unique ID of the membership record inside the organization.
​
request
UpdateOrganizationMemberRequest
required

​
removeOrganizationMember(organizationId, memberId)

Evict a user from the organization. 
await client.organizations.removeOrganizationMember("org_abc123", "mem_123");
​
organizationId
string
required
The exact organization ID.
​
memberId
string
required
The exact ID of the member to evict.

​
Custom RBAC Roles

Wacht allows you to provision custom Roles with specific permissions directly via the API.
  • client.organizations.listOrganizationRoles(organizationId)
  • client.organizations.createOrganizationRole(organizationId, request)
  • client.organizations.updateOrganizationRole(organizationId, roleId, request)
  • client.organizations.deleteOrganizationRole(organizationId, roleId)
await client.organizations.createOrganizationRole("org_abc123", {
  name: "Billing Manager",
  key: "org:billing_manager",
  description: "Can view and modify invoices",
  permissions: ["org:billing:read", "org:billing:write"]
});
​
organizationId
string
required
The exact organization target for the role.
​
request
CreateOrganizationRoleRequest
required