Skip to main content

​
Overview

The Organizations API allows you to create and manage organizations in Hazel Chat. Organizations are the top-level entities that contain members, channels, and settings. This API handles organization lifecycle, slug management, public invite mode, WorkOS domain verification, and admin portal access. All organization operations require authentication and are protected by role-based access control policies. Most operations are restricted to organization admins and owners.

​
Create organization

Creates a new organization and automatically adds the authenticated user as the owner.
​
name
string
required
The organization name.
​
slug
string
URL-friendly slug for the organization. Must be unique across all organizations. If provided and already exists, returns OrganizationSlugAlreadyExistsError.
​
logoUrl
string
URL to the organization’s logo image.
​
settings
object
Custom settings object for organization-specific configuration.

​
Response

​
data
object
required
​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • OrganizationSlugAlreadyExistsError - The provided slug is already in use
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.create", {
  name: "Acme Corporation",
  slug: "acme",
  logoUrl: "https://example.com/logo.png",
  settings: {
    theme: "dark"
  }
});

​
Update organization

Updates an existing organization. Only admins and owners can update organizations.
​
id
string
required
Organization ID to update.
​
name
string
New organization name.
​
slug
string
New slug. Must be unique.
​
logoUrl
string
New logo URL.
​
settings
object
Updated settings object.

​
Response

Returns the same structure as create organization.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • OrganizationSlugAlreadyExistsError - Slug is already taken
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.update", {
  id: "org_123",
  name: "Acme Inc."
});

​
Delete organization

Deletes an organization (soft delete). Only admins and owners can delete organizations.
​
id
string
required
Organization ID to delete.

​
Response

​
transactionId
string
required
Transaction ID for optimistic UI updates.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.delete", {
  id: "org_123"
});

​
Set organization slug

Sets or updates the organization’s slug. Only admins and owners can modify slugs.
​
id
string
required
Organization ID.
​
slug
string
required
New slug value. Must be unique.

​
Response

Returns the same structure as create organization.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • OrganizationSlugAlreadyExistsError - Slug is already taken
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.setSlug", {
  id: "org_123",
  slug: "acme-corp"
});

​
Set public mode

Toggles public invite mode for an organization. When enabled, anyone with the invite URL can join the workspace. Only admins and owners can modify this setting.
​
id
string
required
Organization ID.
​
isPublic
boolean
required
Whether to enable or disable public invite mode.

​
Response

Returns the same structure as create organization.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.setPublicMode", {
  id: "org_123",
  isPublic: true
});

​
Get public organization info

Retrieves limited public information about an organization by slug. No authentication required. Only returns data if the organization has public invites enabled.
​
slug
string
required
Organization slug to look up.

​
Response

​
id
string
Organization ID.
​
name
string
Organization name.
​
slug
string
Organization slug.
​
logoUrl
string
Logo URL.
​
memberCount
number
Number of members in the organization.
Returns null if the organization is not found or does not have public invites enabled.

​
Errors

  • InternalServerError - Unexpected server error
const info = yield* client.call("organization.getBySlugPublic", {
  slug: "acme"
});

if (info) {
  console.log(`${info.name} has ${info.memberCount} members`);
}

​
Join via public invite

Joins an organization via public invite link. Requires authentication. Creates membership with “member” role.
​
slug
string
required
Organization slug from the public invite URL.

​
Response

Returns the same structure as create organization.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • PublicInviteDisabledError - Organization has public invites disabled
  • AlreadyMemberError - User is already a member
  • UnauthorizedError - User is not authenticated
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.joinViaPublicInvite", {
  slug: "acme"
});
Generates a WorkOS Admin Portal link for managing SSO, domain verification, directory sync, audit logs, and log streams. Only admins and owners can access the admin portal.
​
id
string
required
Organization ID.
​
intent
string
required
Portal intent. One of: "sso", "domain_verification", "dsync", "audit_logs", "log_streams".

​
Response

​
link
string
required
WorkOS admin portal URL.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.getAdminPortalLink", {
  id: "org_123",
  intent: "sso"
});

window.open(result.link, "_blank");

​
List domains

Lists all verified and pending domains for an organization. Only admins and owners can list domains.
​
id
string
required
Organization ID.

​
Response

Returns an array of domain objects:
​
id
string
required
Domain ID from WorkOS.
​
domain
string
required
Domain name (e.g., “example.com”).
​
state
string
required
Verification state. One of: "pending", "verified", "failed", "legacy_verified".
​
verificationToken
string
TXT record value for domain verification.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const domains = yield* client.call("organization.listDomains", {
  id: "org_123"
});

for (const domain of domains) {
  console.log(`${domain.domain}: ${domain.state}`);
}

​
Add domain

Adds a domain to an organization for verification. Only admins and owners can add domains.
​
id
string
required
Organization ID.
​
domain
string
required
Domain name to add (e.g., “example.com”).

​
Response

​
id
string
required
Domain ID from WorkOS.
​
domain
string
required
Domain name.
​
state
string
required
Verification state (will be “pending” for new domains).
​
verificationToken
string
TXT record value to add to DNS for verification.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const domain = yield* client.call("organization.addDomain", {
  id: "org_123",
  domain: "example.com"
});

console.log(`Add this TXT record: ${domain.verificationToken}`);

​
Remove domain

Removes a domain from an organization. Only admins and owners can remove domains.
​
id
string
required
Organization ID.
​
domainId
string
required
Domain ID to remove.

​
Response

​
success
boolean
required
Always true on successful deletion.

​
Errors

  • OrganizationNotFoundError - Organization does not exist
  • UnauthorizedError - User lacks permission
  • InternalServerError - Unexpected server error
const result = yield* client.call("organization.removeDomain", {
  id: "org_123",
  domainId: "domain_456"
});

Build docs developers (and LLMs) love

Get started for freeTalk to us