App Invite
Invite users to your application and allow them to sign up.
The App Invite plugin enables you to invite users to your application through email invitations. It supports two types of invitations:
- Personal Invitations: Targeted to specific email addresses, ensuring only the intended recipient can use the invitation
- Public Invitations: Can be used by multiple users, making it ideal for open sign-up scenarios
This plugin is particularly useful for invite-only applications.
Installation
Add the client plugin
Include the App Invite client plugin in your authentication client instance.
Run migrations
This plugin adds an additional table to the database. Click here to see the schema
or generate
Usage
To add members to the application, we first need to send an invitation to the user. The user will receive an email with the invitation link. Once the user accepts the invitation, they will be signed up to the application.
Setup Invitation Email
For personal invites to work we first need to provide 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.
This is only required for personal invites. Sharing public invitations is up to the inviter.
Send Invitation
To invite users to the app, 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 to invite. Leave empty to create a public invitation. -
resend
: A boolean value that determines whether to resend the invitation email, if the user is already invited. Defaults tofalse
-
domainWhitelist
: An optional comma separated list of domains that allows public invitations to be accepted only from approved domains.
Accept Invitation
When a user receives an invitation email, they can click on the invitation link to accept the invitation. The link should include the invitation ID, which will be used to accept the invitation.
Update Invitation Status
To update the status of invitations you can use the acceptInvitation
, rejectInvitation
, cancelInvitation
function provided by the client. The functions take the invitation id as an argument.
Get Invitation
To get an invitation you can use the getAppInvitation
function provided by the client. You need to provide the
invitation id as a query parameter.
List Invitations
Allows an user to list all invitations issued by themself.
By default 100 invitations are returned. You can adjust the limit and offset using the following query parameters:
searchField
: The field to search on, which can beemail
,name
ordomainWhitelist
.searchOperator
: The operator to use for the search. It can becontains
,starts_with
, orends_with
.searchValue
: The value to search for.limit
: The number of invitations to return.offset
: The number of invitations to skip.sortBy
: The field to sort the invitations by.sortDirection
: The direction to sort the invitations by. Defaults toasc
.filterField
: The field to filter the invitations by.filterOperator
: The operator to use for the filter. It can beeq
,ne
,lt
,lte
,gt
orgte
.filterValue
: The value to filter the invitations by.
Schema
The plugin requires an additional table in the database.
Table Name: appInvitation
Fields:
id
: Unique identifier for each invitationname
: The name of the useremail
: The email address of the userinviterId
: The ID of the inviterstatus
: The status of the invitationdomainWhitelist
: A comma separated whitelist of domains for a public invitationexpiresAt
: Timestamp of when the invitation expirescreatedAt
: Timestamp of when the invitation was created
Options
allowUserToCreateInvitation: boolean
| ((user: User, type: "personal" | "public") => Promise<boolean> | boolean)
- A function that determines whether a user can create invite others. By defaults it's true
. You can set it to false
to restrict users from creating invitations.
allowUserToCancelInvitation: (data: { user: User, invitation: AppInvitation }) => Promise<boolean> | boolean
- A functon that determines whether a user can cancel inivtations. By default the user can only cancel invites created by them. You can set it to false
to restrict users from canceling invitations.
invitationExpiresIn: number
- How long the invitation link is valid for in seconds. By default, it's 48 hours (2 days).
sendInvitationEmail: async (data) => Promise<void>
- A function that sends an invitation email to the user. This is only required for personal invitations.
autoSignIn: A boolean value that determines whether to prevent automatic sign-up when accepting an invitation. Defaults to false
.
$Infer.AdditionalFields: Allows you to infer additional data for the user. This option is available in the client plugin aswell.
Shout out
Big shout out to jslno for the initial implementation of the app invite plugin. ❤️