What organizations are, how they work in HelloJohn, and how to build multi-tenant product experiences.

Organizations

Organizations group users within a tenant. They are the building block for multi-tenant product experiences — where your users belong to companies, teams, workspaces, or accounts.

What Is an Organization?

An organization is a named group of users with:

Members — users who belong to the org, each with a role
Roles — owner, admin, and member (custom roles on Pro+)
Metadata — arbitrary key/value data you attach to the org
Invitations — email-based flow to add new members

{
  "id": "org_01HABCDEF777666",
  "tenant_id": "tnt_01HABCDEF654321",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "logo_url": "https://example.com/logo.png",
  "member_count": 12,
  "public_metadata": { "plan": "enterprise" },
  "created_at": "2024-01-10T09:00:00Z"
}

Common Use Cases

Use Case	Pattern
B2B SaaS	Each customer company is an organization
Team workspaces	Each team gets an organization
Project groups	Each project is an organization
Multi-brand	Each brand with its own user base

Organization Roles

Role	Capabilities
`owner`	Full control — manage settings, members, billing
`admin`	Manage members and settings, cannot delete org
`member`	Basic access, no management capabilities

Roles are included in the user's JWT claims when an active organization is selected:

{
  "sub": "usr_01HABCDEF123456",
  "org_id": "org_01HABCDEF777666",
  "role": "admin"
}

Organization Context in JWTs

When a user is in the context of an organization, the JWT includes org_id and the user's role within that org. Your backend can use this to enforce organization-level permissions:

function requireOrgAdmin(req: Request, res: Response, next: NextFunction) {
  const { org_id, role } = req.token;

  if (!org_id) {
    return res.status(403).json({ error: "No active organization" });
  }

  if (!["owner", "admin"].includes(role)) {
    return res.status(403).json({ error: "Admin access required" });
  }

  next();
}

User Memberships

A user can belong to multiple organizations simultaneously. The active organization is selected client-side and reflected in the JWT.

const orgs = await hj.user.getOrganizations(); // List user's orgs
await hj.setActiveOrganization(orgs[0].id);    // Switch active org

Creating Organizations

Organizations can be created by users (self-service) or by admins (programmatic):

// Self-service — user creates their own org
const org = await hj.organizations.create({
  name: "My Company",
  logo_url: "https://example.com/logo.png",
});

// Admin — create on behalf of a user
const org = await hj.admin.organizations.create({
  name: "Customer Corp",
  created_by: "usr_01HABCDEF123456",
});

Personal Organizations

HelloJohn can automatically create a personal organization for each user at sign-up. This simplifies apps where every user starts with their own workspace:

Enable in Tenant Settings → Organizations → Auto-create personal organization.

Organizations

On this page