Create and manage organizations (sub-groups) within tenants in HelloJohn. Members, roles, and invitations within an organization.

Organizations are optional sub-groups within a tenant. Use them when your customers need to divide their workspace into teams, departments, or projects.

Tenant: Acme Corp
├── Org: Engineering  (members: Alice, Bob, Carol)
├── Org: Sales        (members: Dave, Eve)
└── Org: Design       (members: Carol, Frank)

Carol is a member of both Engineering and Design, with different roles in each.

Organizations are optional. If your SaaS doesn't need sub-groups within a customer workspace, skip this section.

Creating an organization

POST /v2/admin/tenants/{tenantId}/orgs
Authorization: Bearer $ADMIN_TOKEN
Content-Type: application/json

{
  "name": "Engineering",
  "slug": "engineering",
  "metadata": { "team_lead": "usr_01HX..." }
}

Response 201 Created:

{
  "id": "org_01HX...",
  "tenant_id": "ten_01HX...",
  "name": "Engineering",
  "slug": "engineering",
  "created_at": "2026-01-15T10:00:00Z"
}

Adding members

POST /v2/admin/tenants/{tenantId}/orgs/{orgId}/members
Content-Type: application/json

{
  "user_id": "usr_01HX...",
  "role": "admin"
}

Roles within an organization:

admin — can manage org members and settings
member — standard member access
Custom roles (if configured in tenant role config)

Listing org members

GET /v2/admin/tenants/{tenantId}/orgs/{orgId}/members

{
  "members": [
    {
      "user_id": "usr_01HX...",
      "email": "alice@acme.com",
      "role": "admin",
      "joined_at": "2026-01-20T10:00:00Z"
    }
  ]
}

Org invitations

Invite users to an organization by email (they don't need to be in the tenant yet):

POST /v2/admin/tenants/{tenantId}/orgs/{orgId}/invitations
Content-Type: application/json

{
  "email": "newmember@acme.com",
  "role": "member",
  "expires_in": 604800  // 7 days
}

The invited user receives an email with a link to accept. On acceptance, HelloJohn creates their account (if needed) and adds them to the org.

Org ID in JWTs

When a user is a member of an organization, the JWT includes org_id:

{
  "sub": "usr_01HX...",
  "tenant_id": "ten_01HX...",
  "org_id": "org_01HX...",
  "roles": ["admin"]
}

If a user belongs to multiple orgs, the org_id reflects the currently selected org. Use switchOrg() in the SDK to change it.

Removing a member

DELETE /v2/admin/tenants/{tenantId}/orgs/{orgId}/members/{userId}

Deleting an organization

DELETE /v2/admin/tenants/{tenantId}/orgs/{orgId}

Deleting an organization removes all memberships. Users remain in the tenant — they're just no longer members of the deleted org.

Organizations