Organization

Organizations simplifies user access and permissions management. Assign roles and permissions to streamline project management, team coordination, and partnerships.

Installation

import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
 
export const auth = await betterAuth({
    database: {
        provider: "sqlite",
        url: "./db.sqlite",
    },
    plugins: [ 
        organization() 
    ] 
})

npx better-auth migrate

import { createAuthClient } from "better-auth/client"
import { organizationClient } from "better-auth/client/plugins"
 
const client = createAuthClient({
    plugins: [ 
        organizationClient() 
    ] 
})

Usage

Once you've installed the plugin, you can start using the organization plugin to manage your organization's members and teams. The client plugin will provide you methods under the organization namespace. And the server api will provide you with the necessary endpoints to manage your organization and gives you easier way to call the functions on your own backend.

Organization

Create an organization

To create an organization, you need to provide:

• name: The name of the organization.
• slug: The slug of the organization.
• logo: The logo of the organization. (Optional)

const data = await client.organization.create({
    name: "My Organization",
    slug: "my-org",
    logo: "https://example.com/logo.png"
})

Restrict who can create an organization

By default, any user can create an organization. To restrict this, set the allowUserToCreateOrganization option to a function that returns a boolean, or directly to true or false.

import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
 
const auth = await betterAuth({
    //...
    plugins: [
        organization({
            allowUserToCreateOrganization: async (user) => { 
                const subscription = await getSubscription(user.id) 
                return subscription.plan === "pro"
            } 
        })
    ]
})

List User's Organizations

To list the organizations that a user is a member of, you can use useListOrganizations hook. It implments a reactive way to get the orSvelteganizations that the user is a member of.

import { client } from "@/auth/client"
 
function App(){
    const { data: organizations } = client.useListOrganizations()
    return (
        <div>
            {organizations.map(org => <p>{org.name}</p>)}
        </div>
    )
} 

Active Organization

Active organization is the workspace the user is currently working on. By defualt when the user is signed in the active organization is set to null.

Set Active Organization

You can set the active organization by calling the organization.setActive function. It'll set the active organization for the user both on the client state and the session on the server.

client.organization.setActive("organization-id")

Use Active Organization

To retrieve the active organization for the user, you can call the useActiveOrganization hook. It returns the active organization for the user. Whenever the active organization changes, the hook will re-evaluate and return the new active organization.

import { client } from "@/auth/client"
 
function App(){
    const { data: activeOrganization } = client.useActiveOrganization()
    return (
        <div>
            {activeOrganization ? <p>{activeOrganization.name}</p> : null}
        </div>
    )
} 

Invitations

To add a member to an organization, we first need to send an invitation to the user. The user will receive an email/sms with the invitation link. Once the user accepts the invitation, they will be added to the organization.

Setup Invitation Email

For member invitation to work we first need to provider sendInvitationEmail to the better-auth instance. This function is responsible for sending the invitation email to the user.

You'll need to construct and send the invitation link to the user. The link should include the invitation ID, which will be used with the acceptInvitation function when the user clicks on it.

import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
import { sendOrganizationInvitation } from "./email"
export const auth = betterAuth({
	plugins: [
		organization({
			async sendInvitationEmail(data) {
                const inviteLink = `https://example.com/accept-invitation/${data.id}`
				sendOrganizationInvitation({
					    email: data.email,
						invitedByUsername: data.inviter.user.name,
						invitedByEmail: data.inviter.user.email,
						teamName: data.organization.name,
						inviteLink
					})
			},
		}),
	],
});

Send Invitation

To invite users to an organization, you can use the invite function provided by the client. The invite function takes an object with the following properties:

• email: The email address of the user.
• role: The role of the user in the organization. It can be admin, member, or guest.
• organizationId: The id of the organization. this is optional by default it will use the active organization. (Optional)

await client.organization.inviteMember({
    email: "[email protected]",
    role: "admin",
})

Accept Invitation

When a user receives an invitation email, they can click on the invitation link to accept the invitation. The invitation link should include the invitation ID, which will be used to accept the invitation.

Make sure to call the acceptInvitation function after the user is logged in.

await client.organization.acceptInvitation({
    invitationId: "invitation-id"
})

Update Invitation Status

To update the status of invitation you can use the acceptInvitation, cancelInvitation, rejectInvitation functions provided by the client. The functions take the invitation id as an argument.

//cancel invitation
await client.organization.cancelInvitation({
    invitationId: "invitation-id"
})
 
//reject invitation (needs to be called when the user who received the invitation is logged in)
await client.organization.rejectInvitation({
    invitationId: "invitation-id"
})

Get Invitation

To get an invitation you can use the getInvitation function provided by the client. You need to provide the invitation id as a query parameter.

client.organization.getInvitation({
    query: {
        id: params.id
    }
})

Remove Memebr

To remove you can use organization.removeMember

//remove member
await client.organization.removeMember({
    memberId: "member-id"
})

Update Member Role

To updadate the role of a member in an organization, you can use the organization.updateMemberRole. If the user has the permission to update the role of the member, the role will be updated.

await client.organization.updateMemberRole({
    memberId: "member-id",
    role: "admin"
})

Access Control

The organization plugin providers a very flexible access control system. You can control the access of the user based on the role they have in the organization. You can define your own set of permissions based on the role of the user.

Roles

currently only three roles are supported:

owner: The user who created the organization by default. The owner has full control over the organization and can perform any action.

admin: Users with the admin role have full control over the organization except for deleting the organization or changing the owner.

member: Users with the member role have limited control over the organization. They can create projects, invite users, and manage projects they have created.

Permissons

By defualt there are 3 resources and they have 2 to 3 actions.

organization:

update delete

member:

create update delete

invitation:

create cancel

The owner have full control over all the resources and actions. The admin have full control over all the resources except for deleting the organization or changing the owner. The member have no control over any of those action other than reading the data.

Custom Permissions

the plugin providers easy way to define your own set of permission for each role.

import { createAccessControl } from "better-auth/plugins/access";
 
/**
 * make sure to use `as const` so typescript can infer the type correctly
 */
const statement = { 
    project: ["create", "share", "update", "delete"], 
} as const; 
 
const ac = createAccessControl(statement); 

import { createAccessControl } from "better-auth/plugins/access";
 
const statement = { 
    project: ["create", "share", "update", "delete"],
} as const; 
 
const ac = createAccessControl(statement); 
 
const member = ac.newRole({ 
    project: ["create"], 
}); 
 
const admin = ac.newRole({ 
    project: ["create", "update"], 
}); 
 
const owner = ac.newRole({ 
    project: ["create", "update", "delete"], 
}); 

import { ac, owner, admin, member } from "@/auth/permissions"
import { betterAuth } from "better-auth"
import { organization } from "better-auth/plugins"
 
export const auth = betterAuth({
    plugins: [
        organization({
            ac: ac,
            roles: {
                owner,
                admin,
                member
            }
        }),
    ],
});

import { createAuthClient } from "better-auth/client"
import { organizationClient } from "better-auth/client/plugins"
import { ac } from "@/auth/permissions"
 
export const client = createAuthClient({
    plugins: [
        organizationClient({
            ac: ac,
        })
    ]
})

Schema

The organization plugin adds the following tables to the database:

Organization

Table Name: organization

Member

Table Name: member

Invitation

Table Name: invitation

Options

allowUserToCreateOrganization: boolean | ((user: User) => Promise<boolean> | boolean) - A function that determines whether a user can create an organization. By default, it's true. You can set it to false to restrict users from creating organizations.

organizationLimit: numbe | ((user: User) => Promise<boolean> | boolean) - The maximum number of organizations allowed for a user. By default, it's 5. You can set it to any number you want or a function that returns a boolean.

creatorRole: admin | owner - The role of the user who creates the organization. By default, it's owner. You can set it to admin.

membershipLimit: number - The maximum number of members allowed in an organization. By default, it's 100. You can set it to any number you want.

sendInvitationEmail: async (data) => Promise<void> - A function that sends an invitation email to the user.

invitationExpiresIn : number - How long the invitation link is valid for in seconds. By default, it's 48 hours (2 days).