Skip to main content

​
Team Invitations

Invite colleagues, team members, or collaborators to join your Budget Bee organization with proper role assignments.

​
Overview

The invitation system allows:
  • Email-based invitations sent directly to new members
  • Role assignment before joining
  • Time-limited invitations (expire after 7 days)
  • Email verification requirement for security
  • Invitation management (cancel pending invitations)

​
Invitation Requirements

To invite members, you must:
  • Have owner or admin role in the organization
  • Organization must have an active Teams subscription
  • Not exceed the 50 member limit
  • Invitee must have or create a verified Budget Bee account

​
Sending Invitations

1

Access Organization Settings

Navigate to Organizations → Settings from the sidebar.
2

Open Invite Dialog

Click the Invite Member button at the top of the page.
3

Enter Invitation Details

​
email
string
required
Email address of the person you want to invite
​
role
enum
required
Role to assign:
  • admin: Can manage members and settings
  • editor: Can create and edit data
  • viewer: Read-only access
4

Send Invitation

Click Send Invitation. The invitee receives an email with an invitation link.
// Invitation email sent via Resend
// From packages/core/auth.ts
sendInvitationEmail: async data => {
  const inviteLink = `${process.env.NEXT_PUBLIC_APP_URL}/invitations/${data.id}`;
  
  const { data: success, error } = await resend.emails.send({
    from: `${process.env.SMTP_SENDER_NAME} <${process.env.SMTP_MAIL}>`,
    to: [data.email],
    subject: `You've been invited to join ${data.organization.name}`,
    html: `
      <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
        <h2>You've been invited!</h2>
        <p>${data.inviter.user.name} has invited you to join 
           <strong>${data.organization.name}</strong> on Budgetbee.</p>
        <p>You'll be joining as a <strong>${data.role}</strong>.</p>
        <p style="margin: 24px 0;">
          <a href="${inviteLink}" 
             style="background-color: #10b981; color: white; 
                    padding: 12px 24px; text-decoration: none; 
                    border-radius: 6px; display: inline-block;">
            Accept Invitation
          </a>
        </p>
        <p style="color: #666; font-size: 14px;">
          This invitation will expire in 7 days.
        </p>
      </div>
    `,
  });
};

​
Invitation Configuration

// From packages/core/auth.ts
organization({
  invitationExpiresIn: 60 * 60 * 24 * 7, // 7 days in seconds
  requireEmailVerificationOnInvitation: true,
  cancelPendingInvitationsOnReInvite: true,
  // ...
})
Invitations expire after 7 days for security. Expired invitations can be resent.

​
Accepting Invitations

When someone receives an invitation:
1

Receive Email

The invitee receives an email with invitation details and a link.
2

Click Invitation Link

Clicking the link takes them to /invitations/[id] in Budget Bee.
3

Sign In or Sign Up

If not logged in:
  • Existing users: Sign in with their credentials
  • New users: Create an account first
Email verification is required before accepting invitations.
4

Review Invitation

The invitation page shows:
  • Organization name
  • Role being assigned
  • Who sent the invitation
5

Accept or Decline

Choose to Accept or Decline the invitation.If accepted:
  • User is added to the organization
  • Assigned the specified role
  • Redirected to organization settings
// From apps/web/app/(app)/invitations/[id]/page.tsx
export default function InvitationPage({ params }) {
  const invitationId = React.use(params).id;
  const { mutateAsync: acceptInvitation } = useAcceptInvitation();
  const { mutateAsync: rejectInvitation } = useRejectInvitation();

  const handleAccept = async () => {
    try {
      await acceptInvitation(invitationId);
      router.push("/organizations/settings")
    } catch (err) {
      setError(err.message);
    }
  };

  const handleReject = async () => {
    try {
      await rejectInvitation(invitationId);
      router.push("/home")
    } catch (err) {
      setError(err.message);
    }
  };

  return (
    <Card>
      <CardHeader>
        <CardTitle>Organization Invitation</CardTitle>
        <CardDescription>
          You've been invited to join an organization.
        </CardDescription>
      </CardHeader>
      <CardFooter>
        <Button variant="destructive" onClick={handleReject}>
          Decline
        </Button>
        <Button onClick={handleAccept}>
          Accept
        </Button>
      </CardFooter>
    </Card>
  );
}

​
Managing Invitations

View and manage pending invitations:

​
Viewing Pending Invitations

1

Go to Organization Settings

Navigate to Organizations → Settings.
2

Select Pending Invitations Tab

Click the Pending Invitations tab to see all outstanding invitations.
3

Review Invitations

Each invitation shows:
  • Recipient email
  • Assigned role
  • Who sent it
  • When it was sent
  • Expiration date
  • Status (pending, expired)

​
Canceling Invitations

Owners and admins can cancel pending invitations:
1

Locate Invitation

Find the invitation in the pending invitations list.
2

Cancel Invitation

Click the Cancel button next to the invitation.
3

Confirm Cancellation

Confirm that you want to cancel. The invitation link becomes invalid.
If someone hasn’t accepted an invitation, cancel and resend it. This generates a fresh link and resets the expiration.

​
Resending Invitations

If an invitation expires or is lost:
  1. Cancel the old invitation
  2. Send a new invitation to the same email
  3. The configuration cancelPendingInvitationsOnReInvite: true automatically cancels old invitations

​
Invitation Limits

  • Maximum pending invitations: No hard limit, but consider the 50 member maximum
  • Invitations per user: One active invitation per email address
  • Re-invitation cooling period: None, you can immediately resend

​
Email Verification Requirement

For security, invitations require email verification:
1

Invitee Creates Account

New users sign up with the invited email address.
2

Verify Email

They must verify their email before accepting the invitation.
3

Accept Invitation

Once verified, they can click the invitation link and accept.
Invitations sent to unverified emails cannot be accepted until the user verifies their account.

​
Invitation Status

Invitations can have different statuses:
  • Pending: Invitation sent, awaiting response
  • Accepted: User accepted and joined the organization
  • Rejected: User declined the invitation
  • Expired: 7 days passed without acceptance
  • Canceled: Invitation canceled by admin or owner

​
Security Considerations

Email Verification

Prevents unauthorized users from joining your organization.

Time Limits

7-day expiration reduces the window for link misuse.

Single Use

Invitation links can only be used once.

Cancellable

Admins can immediately invalidate invitations if needed.

​
Best Practices

Verify Email First

Ensure the recipient’s email address is correct before sending.

Set Appropriate Roles

Assign the minimum necessary role for the member’s responsibilities.

Follow Up

Contact the recipient to let them know an invitation is coming.

Track Expirations

Regularly check for expired invitations and resend as needed.

​
Common Invitation Workflows

​
Onboarding New Employee

1

Create Company Email

Ensure the employee has a company email address.
2

Send Invitation

Invite with editor role for most employees.
3

Provide Instructions

Send onboarding documentation explaining Budget Bee usage.
4

Verify Acceptance

Check that they accepted within 1-2 days.

​
Adding External Accountant

1

Discuss Access Level

Determine if they need editor (to enter data) or viewer (to review only).
2

Send Invitation

Use their professional email address.
3

Set Expectations

Clarify what data they’ll have access to.

​
Troubleshooting

Check:
  • Email address is spelled correctly
  • Check spam/junk folder
  • Verify sender domain isn’t blocked
  • Confirm Resend API is configured correctly
  • Try resending the invitation
Verify:
  • Email address is verified
  • Invitation hasn’t expired (check date)
  • You’re signed in with the invited email address
  • Invitation wasn’t canceled by an admin
  • Invitation link wasn’t already used
Ensure:
  • You have admin or owner role
  • Organization has active Teams subscription
  • Haven’t reached 50 member limit
  • Email address isn’t already a member
  • Email address format is valid
Simple fix:
  • Cancel the expired invitation
  • Send a new invitation
  • New invitation has a fresh 7-day window

​
Database Schema

Invitations are stored in the database: 
create table invitations (
  id text primary key,
  organization_id text references organizations(id) on delete cascade,
  email text not null,
  role text not null,
  status text not null,
  inviter_id text references users(id),
  created_at timestamp default current_timestamp,
  expires_at timestamp not null
);

​
Next Steps

Understand Roles

Learn about different roles and their permissions.

Manage Organization

Overview of organization features and management.

Build docs developers (and LLMs) love

Get started for freeTalk to us