Managing Organizations

This guide covers how to create, read, update, and delete organizations using the HelloJohn API and React SDK.

Creating an Organization

Via SDK

import { useHelloJohn } from "@hellojohn/react";

function CreateOrgForm() {
  const { organizations } = useHelloJohn();

  const handleCreate = async (name: string) => {
    const org = await organizations.create({ name });
    console.log("Created:", org.id);
  };

  return (
    <form onSubmit={(e) => {
      e.preventDefault();
      handleCreate(new FormData(e.currentTarget).get("name") as string);
    }}>
      <input name="name" placeholder="Organization name" required />
      <button type="submit">Create</button>
    </form>
  );
}

Via API

curl -X POST https://api.hellojohn.dev/v1/organizations \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "created_by": "usr_01HABCDEF123456"
  }'

The created_by user is automatically added as owner.

Listing Organizations

All orgs in tenant (admin)

curl "https://api.hellojohn.dev/v1/organizations" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

User's orgs (client-side)

const { user } = useHelloJohn();
const myOrgs = await user.getOrganizations();

Updating an Organization

curl -X PATCH "https://api.hellojohn.dev/v1/organizations/org_01HABCDEF777666" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "logo_url": "https://example.com/new-logo.png"
  }'

Only owner and admin members can update an organization.

Deleting an Organization

Deleting an organization removes all memberships. Users are not deleted.

curl -X DELETE "https://api.hellojohn.dev/v1/organizations/org_01HABCDEF777666" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Response: 204 No Content

Only the owner can delete an organization. Admins cannot.

Organization Settings UI

Build an organization settings page using the SDK:

import { useOrganization } from "@hellojohn/react";

function OrgSettings() {
  const { organization, update, isLoading } = useOrganization();

  if (isLoading) return <p>Loading...</p>;

  return (
    <div>
      <h2>{organization.name}</h2>
      <form
        onSubmit={async (e) => {
          e.preventDefault();
          const data = new FormData(e.currentTarget);
          await update({ name: data.get("name") as string });
        }}
      >
        <input
          name="name"
          defaultValue={organization.name}
          placeholder="Organization name"
        />
        <button type="submit">Save</button>
      </form>
    </div>
  );
}

Organization Slugs

Every organization has a URL-safe slug used in URLs and as an alternative to the ID. If you don't provide a slug, HelloJohn generates one from the name:

"Acme Corp" → acme-corp
"My Team" → my-team

Fetch by slug:

GET /v1/organizations/slug/acme-corp

Access Control

Operation	Required Role
Create org	Any authenticated user
Read org	Any org member
Update org (name, logo)	`admin`, `owner`
Delete org	`owner` only
Manage members	`admin`, `owner`
Transfer ownership	`owner` only

Managing Organizations

On this page