Skip to main content
Quickly integrate a complete invitation flow into your service.

​
1. Sign up for Vortex

Go to http://admin.vortexsoftware.com/signup and sign up. Once you’re in Vortex you’ll see the invitation flow that we’ve already created for you. Click on it to have a look!

​
2. Enter Landing Page URLs

The landing page URL is the page invitees are taken to when clicking on an invitation link. Typically this would be your signup page. Click on the Landing Page tab and enter the URL for, at a minimum, your development environment.

​
3. Get Your API Key

Click on the Set up Server tab and you’ll be prompted to create an API key. Go ahead and create the API key for your development environment and be sure to copy it and save it somewhere, as you won’t be able to access it again.

​
4. Get Your Widget ID

If it was not already provided to you, get your widget ID by clicking on the Install Client tab and looking for the value of the widgetId parameter in the code snippet.

​
5. Render the Invitation Widget (Client)

  • React
  • Angular
  • Vue
  • JavaScript
Install the Vortex package:
  • npm
  • yarn
  • pnpm
npm install @teamvortexsoftware/vortex-react

import { VortexInvite } from "@teamvortexsoftware/vortex-react"
If you have an existing modal that displays an invitation form, replace the contents of that modal with the invitation widget from Vortex by using the following code snippet:
<VortexInvite
  widgetId="00000000-0000-0000-0000-000000000000"
  user={{ 
    userId: '00000000-0000-0000-0000-000000000000', 
    identifiers: [{type: 'email', value: 'sally@acme.com'}], 
    groups: [{ id: 'someId', type: 'workspace', name: 'Acme Workspace' }]}}
  group={{ 
    groupId: "12345678",
    type: "workspace", 
    name: "Acme Workspace" }}. 
 />
If users of your service are grouped together in some fashion (e.g., workspace, org, team, etc.) you should populate the group parameter with information about the group to which the invitee is being invited. Otherwise you should leave it out. The user parameter provides information about the current user (i.e., inviter). In development you can send it as unsigned JSON, as in the example above, but in higher environments it must be sent as a signed JWT. The user.groups parameter represents the group(s) that the current user is in, and it can be left out if your users aren’t grouped. Otherwise, for security reasons, group.groupId must be represented in user.groups. Refer to the Install Client section for a complete list of parameters.

​
6. Build the Invitation Acceptance Flow (Server)

Complete SDK documenation can be found in our public repos on GitHub, but the instructions below cover what you need to get started.
  • Next.js
  • Node
  • Go
  • PHP
  • Python
1

Configuration

Generate required files:
npm install @teamvortexsoftware/vortex-nextjs-15-sdk @teamvortexsoftware/vortex-react-provider
npx vortex-setup
Set the following environment variable:
VORTEX_API_KEY=your_api_key
Edit lib/vortex-config.ts to implement your authentication and access control:
import { configureVortexLazy, createAllowAllAccessControl } from '@teamvortexsoftware/vortex-nextjs-15-sdk';

configureVortexLazy(async () => ({
  apiKey: process.env.VORTEX_API_KEY!,

  // Required: How to authenticate users
  authenticateUser: async (request) => {
    const user = await getCurrentUser(request); // Your auth logic
    return user ? {
      userId: user.id,
      identifiers: [{ type: 'email', value: user.email }],
      groups: user.groups, // [{ type: 'team', groupId: '123', name: 'My Team' }]
    } : null;
  },

  // Simple: Allow all operations (customize for production)
  ...createAllowAllAccessControl(),
}));
2

Parse the invitation ID

When an invitee clicks on an invitation they are redirected to the landing page specified in your invitation flow’s configuration with the ID of the invitation passed in on the query string.https://acme-tasks.com/invites/accept?invitationId=3457f7fd-a312-40a5-8284-4c2f87c8aed1Persist the invitation ID through your registration process, so that you can later mark the invitation as accepted.
3

Get invitation details

Using the invitation ID to get all of the information about the invitation, including the inviter’s ID and email address, the invitee’s email address (unless it’s a shareable link), the group the invitation is associated with (ID, type, name) and any custom field values collected during the invitation process (e.g., Role).
import { createVortexInvitationRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';

export const { GET, DELETE } = createVortexInvitationRoute();
If the endpoint returns a 404 the invitation is no longer valid and you should provide appropriate messaging to the invitee.For most services an invitation will be associated with a specific group (e.g., workspace, organization, team, document, etc.). You should confirm that the group the invitation is associated with is still valid before allowing the user to accept the invitation.
4

Mark the invitation as accepted

After the user signs up, notify Vortex that the invitation was accepted.
import { createVortexInvitationsAcceptRoute } from '@teamvortexsoftware/vortex-nextjs-15-sdk';

export const { POST } = createVortexInvitationsAcceptRoute();