Invitations

In a SaaS platform, inviting other users to join your organization fosters collaboration. Most SaaS platforms target businesses, which often involve entire teams. Invitations streamline the process of onboarding these team members effectively.

Model

An invitation requires an email, a role and a token to uniquely identify and track it.

export const invitationTable = pgTable(  'invitation',  {    id: uuid('id').primaryKey().notNull().defaultRandom(),    organizationId: uuid('organizationId')      .notNull()      .references(() => organizationTable.id, {        onDelete: 'cascade',        onUpdate: 'cascade'      }),    token: uuid('token').notNull().defaultRandom(),    email: varchar('email', { length: 255 }).notNull(),    role: roleEnum('role').default(Role.MEMBER).notNull(),    status: invitationStatusEnum('status')      .default(InvitationStatus.PENDING)      .notNull(),    lastSentAt: timestamp('lastSentAt', { precision: 3, mode: 'date' })  },  (table) => [    index('IX_invitation_organizationId').using(      'btree',      table.organizationId.asc().nullsLast().op('uuid_ops')    ),    index('IX_invitation_token').using(      'btree',      table.token.asc().nullsLast().op('uuid_ops')    )  ]);

State

An invitation can be in one of three states:

• Pending: The invitation has been sent but not yet accepted.
• Accepted: The user has accepted the invitation and joined the organization.
• Revoked: The invitation has been invalidated, either manually or due to specific actions (e.g., account deletion).

Email flow

When you invite a user, an email containing a link with a securely encrypted verification token is sent. This token ensures that only the recipient can accept the invitation.

Invitation email

The email includes:

• A personalized message introducing the invitation.
• A call-to-action button linking to the platform with the token pre-embedded.
• Information about the inviting organization, including name and description.

Onboarding

If the invited user does not already have an account, Achromatic handles the invitation during the signup process. This integration avoids the need for the user to navigate back and forth between steps, streamlining the onboarding experience.

• Existing User: If the invited user already has an account, they will be prompted to accept the invitation and immediately join the organization.

• New User: For new users, the invitation is automatically linked to their onboarding flow. After completing registration, they are seamlessly added to the organization.

Expiration

Invitations do not expire. This is on purpose because it has no further implications.

Automatic invalidation

An invitation is automatically revoked in the following scenarios:

• The user accepts the invitation: Once accepted, the token becomes invalid.
• The user changes their email address: To prevent misuse, any changes to the associated email automatically invalidate the token.
• The user deletes their account: Invitations linked to a deleted account are revoked to maintain data integrity.

This ensures that invitations remain secure and aligned with the current state of user accounts.

Invitation management

Admins can manage invitations via a dedicated section in the dashboard, where they can:

• View the status of all invitations (Pending, Revoked).
• Resend invitations who did not respond.
• Revoke invitations if they were sent to the wrong email or are no longer needed.
• Adjust the role of an invitation if not yet accepted