Organization Management

In a multi-tenant SaaS, organizations are your customers' workspaces. Each organization has its own users, roles, subscription, API keys, and data. The admin panel gives you full visibility into every organization on your platform and the ability to manage them when needed.

Why This Matters

Your users interact with your product through their organization. When a customer says "our workspace is broken" or "we need to upgrade," you need to find their organization quickly, understand its current state, and take action. Without an admin view, this means running database queries. With the AdminOrganizationController, it is a quick search and a few clicks.

List and Search Organizations

GET /api/admin/organizations

Returns a paginated list of all organizations. Supports search and filtering via query parameters.

GET /api/admin/organizations?search=acme&page=1

• Search matches against organization name
• Results include owner information, member count, subscription status, and creation date

When to Use This

Common scenarios where you will search for organizations:

• Customer support: A customer emails saying they have a billing issue. Search by their company name to find their organization, see their current plan, and check their subscription status.
• Sales follow-up: Your sales team wants to know which organizations are on the free plan with the most members -- they are the best candidates for upgrade outreach. Browse the list sorted by member count and filter by plan.
• Plan audit: You want to see how many organizations are on each plan tier. The list view shows subscription status alongside each organization, giving you a quick breakdown.
• Abuse investigation: You notice unusual API usage patterns. Search for the organization generating the traffic to review their account and decide whether to contact them or take action.

View Organization Details

GET /api/admin/organizations/{id}

Returns full details for a single organization, including:

• Organization name, slug, and creation date
• Owner information
• All members with their roles
• Current subscription plan and billing status
• Usage statistics and resource consumption

When to Use This

When a customer contacts support with a specific issue, the detail view gives you everything you need in one place. You can see who owns the organization, how many members it has, what plan they are on, and whether their subscription is active. This is also useful for understanding your power users -- the organizations that use your product the most are the ones whose feedback matters the most.

Delete Organization

DELETE /api/admin/organizations/{id}

Permanently deletes an organization and all associated data. This action requires super_admin and is irreversible.

When to Use This

• Customer cancellation with data removal: A customer cancels their subscription and requests that all their data be deleted. This fulfills that request in a single action.
• GDPR/compliance requests: When a company requests deletion of all data associated with their account, this endpoint handles the complete cleanup.
• Test organization cleanup: During development or after demos, you may have test organizations that need to be removed to keep the platform clean.
• Abuse response: An organization is being used for abusive purposes and needs to be removed entirely, not just suspended.

What Gets Deleted (Cascading)

When an organization is deleted, the following associated data is removed as part of the operation:

• Memberships: All user-organization relationships are removed. The users themselves are not deleted -- they retain their accounts and any other organization memberships.
• Subscriptions: Active subscriptions are cancelled in the billing gateway (Stripe) before being removed from the database. This ensures the customer is not charged going forward.
• API keys: All API keys issued to the organization are revoked immediately. Any external integrations using those keys will stop working.
• Invitations: Pending invitations to join the organization are deleted. Anyone with an outstanding invitation link will see an error if they try to accept it.
• Files: Organization-scoped files are removed from storage (S3/R2). This includes any uploads, attachments, or assets associated with the organization.

Audit and Compliance

The deletion is recorded in the audit log with the full organization details -- name, owner, member count, plan, and the admin who performed the deletion. This audit entry is preserved even after the organization data is gone, giving you a compliance trail that proves the deletion was performed, when it happened, and who authorized it. This is essential for responding to regulatory inquiries about data handling.