Organization

Neon Auth is built on Better Auth and comes with a pre-configured Organization plugin, so your app can support multi-tenancy without additional setup.

Why use this plugin?

Use the Organization plugin when you need multi-tenancy in your app. It supports:

• Multi-tenant apps where each tenant is an organization
• Workspaces or groups that share a Neon branch (same database)
• Inviting users and assigning roles: owner, admin, or member
• Role-based access: owners and admins can manage the org; the member role has read-only access

Better Auth also has a Teams feature (sub-groups within an org); that feature is not currently enabled in Neon Auth.

Prerequisites

• A Neon project with Auth enabled
• A signed-in user (organizations are associated with users)

Example application

neon-auth-orgs-example is a multi-tenant sample that uses the Organization plugin with Drizzle and @neondatabase/auth (see that folder’s README for bun setup from the monorepo root). For other runnable Neon Auth apps, see Example applications.

Configure the organization plugin

The Organization plugin is enabled by default for each branch; you can disable it or change settings in the Console or via the API. If the plugin is disabled, your application users and admins cannot create or manage organizations, and any organization-related API calls will return an error.

Organizations

Use the following methods to manage the organization lifecycle.

Create an organization

Creates a new organization. The user creating it automatically becomes the Owner.

const { data, error } = await authClient.organization.create({
  name: 'My Organization',
  slug: 'my-org',
  logo: 'https://example.com/logo.png',
  metadata: { plan: 'pro' },
  keepCurrentActiveOrganization: false,
});

Check organization slug

Checks if an organization slug is available.

const { data, error } = await authClient.organization.checkSlug({
  slug: 'my-org',
});

List organizations

Lists all organizations the current user is a member of.

const { data, error } = await authClient.organization.list();

In a React component, you can use the useListOrganizations hook to fetch and display organizations:

import { authClient } from './auth';

export default function OrganizationList() {
  const { data: organizations } = authClient.useListOrganizations();
  return (
    <div>
      {organizations?.map((org) => (
        <p>{org.name}</p>
      ))}
    </div>
  );
}

Set active organization

Switches the user's active context to a specific organization.

const { data, error } = await authClient.organization.setActive({
  organizationId: 'org_12345678',
});

Get active organization

Retrieves full details of the currently active organization.

const { data, error } = await authClient.organization.getFullOrganization({
  query: {
    organizationId: 'org-id',
    organizationSlug: 'org-slug',
    membersLimit: 10,
  },
});

In a React component, you can use the useActiveOrganization hook to fetch and display the active organization:

import { authClient } from './auth';

export default function ActiveOrganization() {
  const { data: organization } = authClient.useActiveOrganization();
  return (
    <div>
      <h1>{organization?.name}</h1>
      <p>Members: {organization?.members.length}</p>
    </div>
  );
}

Update organization

Updates organization details. Requires Owner or Admin permissions.

await authClient.organization.update({
  data: {
    name: 'New Name',
    metadata: { plan: 'enterprise' },
  },
  organizationId: 'org-id',
});

Delete organization

Deletes the organization and all associated data. Requires Owner permission.

const { data, error } = await authClient.organization.delete({
  organizationId: 'org-id',
});

Invitations

Manage invitations to join an organization.

Invite member

Sends an invitation to a user.

const { data, error } = await authClient.organization.inviteMember({
  email: 'new-user@example.com',
  role: 'member',
  resend: true,
});

Accept invitation

Accepts an invitation using the invitation ID.

const { data, error } = await authClient.organization.acceptInvitation({
  invitationId: 'invitation-id',
});

Reject invitation

Declines an invitation that the user has received and chooses not to accept.

const { data, error } = await authClient.organization.rejectInvitation({
  invitationId: 'invitation-id',
});

Cancel invitation

Cancel a pending invitation that has been sent to a user.

const { data, error } = await authClient.organization.cancelInvitation({
  invitationId: 'invitation-id',
});

Get invitation

Retrieves details of a specific invitation.

const { data, error } = await authClient.organization.getInvitation({
  query: {
    id: 'invitation-id',
  },
});

List invitations

Lists all pending invitations for an organization.

const { data, error } = await authClient.organization.listInvitations({
  query: {
    organizationId: 'org-id',
  },
});

List user invitations

Lists all invitations received by the current user.

const { data, error } = await authClient.organization.listUserInvitations();

Members

Manage users within the organization.

List members

Lists members with support for pagination, sorting, and filtering.

const { data, error } = await authClient.organization.listMembers({
  query: {
    limit: 20,
    offset: 0,
    sortBy: 'createdAt',
    sortDirection: 'desc',
    filterField: 'role',
    filterOperator: 'eq',
    filterValue: 'admin',
  },
});

Update member role

Updates a member's role.

const { data, error } = await authClient.organization.updateMemberRole({
  memberId: 'member-id',
  role: 'admin',
});

Remove member

Removes a member from the organization.

const { data, error } = await authClient.organization.removeMember({
  memberIdOrEmail: 'member-id-or-email',
});

Get active member

Gets the current user's membership details for the active organization.

const { data, error } = await authClient.organization.getActiveMember();

Get Active Member Role

Gets the current user's role(s) in the active organization.

const { data, error } = await authClient.organization.getActiveMemberRole();

Leave organization

Removes the current user from an organization.

const { data, error } = await authClient.organization.leave({
  organizationId: 'org-id',
});

Access Control

The Organization plugin includes a Role-Based Access Control (RBAC) system.

You can check permissions on the client side using checkRolePermission:

const canDelete = authClient.organization.checkRolePermission({
  permission: {
    organization: ['delete'],
  },
  role: 'admin', // returns false, admins cannot delete orgs
});
// console.log(canDelete); // false

Limitations

Because Neon Auth is a managed service, some Better Auth features are not currently supported:

• Teams: The Teams sub-feature is not currently enabled.
• Hooks: Server-side hooks (for example, beforeCreateOrganization) are not supported.
• Custom Permissions: You cannot currently define custom roles or modify default permissions.
• Dynamic Access Control: Dynamic creation of roles via API is not enabled.

Check the Neon Auth roadmap for updates on these features.