Administrative operations for managing organizations — bulk actions, impersonation, and admin-only APIs.

Organization Admin

This guide covers administrative operations performed by tenant admins (using secret keys), as opposed to organization-level operations performed by org owners.

Admin vs. Org Owner

Actor	Credentials	Scope
Org Owner	User's session token	Manage a single org they own
Tenant Admin	`sk_live_` secret key	Manage all orgs in the tenant

Listing All Organizations

Tenant admins can list all organizations across the tenant:

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

Query parameters:

Parameter	Type	Description
`q`	string	Search by name or slug
`member_id`	string	Filter by member user ID
`created_after`	ISO date	Filter by creation date
`limit`	integer	Default `20`, max `100`
`cursor`	string	Pagination cursor

Creating Organizations on Behalf of Users

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": "Customer Corp",
    "slug": "customer-corp",
    "created_by": "usr_01HABCDEF123456",
    "public_metadata": {"plan": "starter"}
  }'

The created_by user is automatically added as owner.

Force-Adding Members

Admins can add users to any organization without going through the invitation flow:

curl -X POST "https://api.hellojohn.dev/v1/organizations/org_01HABCDEF777666/members" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_01HABCDEF789012",
    "role": "member"
  }'

Force-Removing Members

Admins can remove any member from any organization:

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

Deleting an Organization (Admin Override)

Tenant admins can delete any organization, even if they are not a member:

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

All members are removed. The organization and its metadata are permanently deleted.

Auditing Organization Activity

Query the audit log filtered to organization events:

curl "https://api.hellojohn.dev/v1/admin/audit-logs?resource_type=organization&from=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "X-Tenant-ID: tnt_01HABCDEF654321"

Organization audit events:

Action	Description
`org.created`	Organization was created
`org.updated`	Name, slug, or metadata changed
`org.deleted`	Organization was deleted
`org.member.added`	Member was added
`org.member.removed`	Member was removed
`org.member.role_changed`	Member's role was updated
`org.invitation.sent`	Invitation was sent
`org.invitation.accepted`	Invitation was accepted
`org.invitation.revoked`	Invitation was cancelled

Updating Organization Metadata (Admin)

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 '{
    "private_metadata": {
      "stripe_customer_id": "cus_new123",
      "internal_id": 42
    }
  }'

Only tenant admins with a secret key can write private_metadata.

Org Stats

Get member and activity stats for a specific org:

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

Response:

{
  "organization_id": "org_01HABCDEF777666",
  "members": {
    "total": 12,
    "by_role": {
      "owner": 1,
      "admin": 2,
      "member": 9
    }
  },
  "invitations": {
    "pending": 3
  },
  "created_at": "2024-01-10T09:00:00Z"
}

Organization Admin

On this page