Installation
Quick Start
Generate a secure token for Vortex componentsIntegration Flow
Vortex uses a split architecture: your backend signs tokens with the SDK, and your frontend renders components that use those tokens to securely interact with Vortex.Generate a token for the current user
When a user loads a page with a Vortex component, generate a signed token on your server
Methods
Core Methods
generateToken()
Generate a signed token for use with Vortex widgets
| Name | Type | Required | Description | |
|---|---|---|---|---|
payload | array | ✓ | Data to sign (user, component, scope, vars, etc.) | |
options | `array | null` | ✓ | Optional configuration (expiresIn) |
string — Signed JWT token
Example
Example
getInvitation()
Get a specific invitation by ID public function getInvitation(string $invitationId): array
| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID |
array — The invitation data
acceptInvitation()
Accept a single invitation (recommended method) This is the recommended method for accepting invitations.
| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | Single invitation ID to accept |
user | array | ✓ | User array with ‘email’/‘phone’/‘name’ keys |
array — The accepted invitation result
Example
Example
Additional Methods
Additional Methods
getInvitationsByTarget()
Get invitations by target (email or sms) public function getInvitationsByTarget(string targetValue): array| Name | Type | Required | Description |
|---|---|---|---|
targetType | string | ✓ | Type of target (‘email’ or ‘phone’) |
targetValue | string | ✓ | Target value (email address or phone number) |
array — List of invitationsrevokeInvitation()
Revoke (delete) an invitation public function revokeInvitation(string $invitationId): array| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID to revoke |
array — Success responseacceptInvitations()
Accept multiple invitations Supports three formats: 1. User array (preferred): [‘email’ => ’…’, ‘phone’ => ’…’, ‘name’ => ’…’] 2. Target array (deprecated): [‘type’ => ‘email’, ‘value’ => ’…’] 3. Array of targets (deprecated): [[‘type’ => ‘email’, ‘value’ => ’…’], …]| Name | Type | Required | Description |
|---|---|---|---|
invitationIds | array | ✓ | List of invitation IDs to accept |
userOrTarget | array | ✓ | User array with ‘email’/‘phone’/‘name’ keys, OR legacy target(s) |
array — The accepted invitation resultExample
Example
deleteInvitationsByScope()
Delete all invitations for a specific group public function deleteInvitationsByScope(string scope): array| Name | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | The group type |
scope | string | ✓ | The group ID |
array — Success responsegetInvitationsByScope()
Get all invitations for a specific group public function getInvitationsByScope(string scope): array| Name | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | The group type |
scope | string | ✓ | The group ID |
array — List of invitations for the groupreinvite()
Reinvite a user (send invitation again) public function reinvite(string $invitationId): array| Name | Type | Required | Description |
|---|---|---|---|
invitationId | string | ✓ | The invitation ID to reinvite |
array — The reinvited invitation resultgetAutojoinDomains()
Get autojoin domains configured for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | The type of scope (e.g., “organization”, “team”, “project”) |
scope | string | ✓ | The scope identifier (customer’s group ID) |
array — Response with ‘autojoinDomains’ array and ‘invitation’Example
Example
configureAutojoin()
Configure autojoin domains for a specific scope This endpoint syncs autojoin domains - it will add new domains, remove domains not in the provided list, and deactivate the autojoin invitation if all domains are removed (empty array).| Name | Type | Required | Description | |
|---|---|---|---|---|
scope | string | ✓ | The scope identifier (customer’s group ID) | |
scopeType | string | ✓ | The type of scope (e.g., “organization”, “team”) | |
domains | array | ✓ | Array of domain strings to configure for autojoin | |
componentId | string | ✓ | The component ID | |
scopeName | `string | null` | ✓ | Optional display name for the scope |
metadata | `array | null` | ✓ | Optional metadata to attach to the invitation |
array — Response with ‘autojoinDomains’ array and ‘invitation’Example
Example
Types
Type Definitions
Type Definitions
GenerateTokenPayload
Payload for generateToken() - used to generate secure tokens for Vortex components| Field | Type | Required | Description |
|---|---|---|---|
user | TokenUser | The authenticated user who will be using the Vortex component | |
component | string | Component ID to generate token for (from your Vortex dashboard) | |
scope | string | Scope identifier to restrict invitations (format: “scopeType:scopeId”) | |
vars | array | Custom variables to pass to the component for template rendering |
TokenUser
User data for token generation - represents the authenticated user sending invitations| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for the user in your system. Used to attribute invitations. |
email | string | User’s email address. Used for reply-to in invitation emails. | |
name | string | Display name shown to invitation recipients (e.g., “John invited you”) | |
avatarUrl | string | URL to user’s avatar image. Displayed in invitation emails and widgets. | |
adminScopes | string[] | List of scope IDs where this user has admin privileges | |
allowedEmailDomains | string[] | Restrict invitations to specific email domains (e.g., [“acme.com”]) |
AcceptUser
User data for accepting invitations - identifies who accepted the invitation| Field | Type | Required | Description |
|---|---|---|---|
email | string | Email address of the accepting user. At least one of email or phone is required. | |
phone | string | Phone number with country code. At least one of email or phone is required. | |
name | string | Display name of the accepting user (shown in notifications to inviter) | |
isExisting | bool | Whether user was already registered. true=existing, false=new signup, null=unknown. |
CreateInvitationTarget
Target specification when creating an invitation - where to send the invite| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Delivery channel: “email”, “phone”, “share”, or “internal” |
value | string | ✓ | Target address: email address, phone number with country code, or internal user ID |
name | string | Display name of the recipient (used in email greetings) |
CreateInvitationScope
Scope specification when creating an invitation - what group/team to invite into| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Scope type (e.g., “team”, “organization”, “workspace”) |
groupId | string | ✓ | Your internal identifier for this scope/group |
name | string | ✓ | Display name for the scope (shown in invitation emails) |
Identifier
Email or phone identifier for looking up users| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Identifier type: “email” or “phone” |
value | string | ✓ | The email address or phone number (with country code for phone) |
ConfigureAutojoinRequest
Request to configure autojoin domains for a scope| Field | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | Type of scope (e.g., “team”, “workspace”) |
scopeId | string | ✓ | Your internal identifier for the scope |
domains | string[] | ✓ | List of email domains to enable autojoin for (e.g., [“acme.com”]) |
SyncInternalInvitationRequest
Request to sync an internal invitation (for tracking invitations made outside Vortex)| Field | Type | Required | Description |
|---|---|---|---|
inviterId | string | ✓ | Your internal user ID for the person who sent the invitation |
target | CreateInvitationTarget | ✓ | The invitation recipient |
scopes | CreateInvitationScope[] | Scopes/groups the invitation grants access to |
InvitationResult
Complete invitation details as returned by the Vortex API| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this invitation |
accountId | string | ✓ | Your Vortex account ID |
clickThroughs | int | ✓ | Number of times the invitation link was clicked |
createdAt | string | ✓ | ISO 8601 timestamp when the invitation was created |
deactivated | bool | ✓ | Whether this invitation has been revoked or expired |
deliveryCount | int | ✓ | Number of times the invitation was sent (including reminders) |
deliveryTypes | string[] | ✓ | Channels used to deliver: “email”, “phone”, “share”, “internal” |
foreignCreatorId | string | ✓ | Your internal user ID for the person who created this invitation |
invitationType | string | ✓ | Type: “single_use”, “multi_use”, or “autojoin” |
status | string | ✓ | Current status: queued, sending, sent, delivered, accepted, shared |
target | InvitationTarget[] | ✓ | List of invitation recipients with their contact info and status |
views | int | ✓ | Number of times the invitation page was viewed |
groups | InvitationScope[] | ✓ | Scopes (teams/orgs) this invitation grants access to |
expired | bool | ✓ | Whether this invitation has passed its expiration date |
expires | string | ISO 8601 timestamp when this invitation expires | |
inviter | Inviter | Information about who sent the invitation |
InvitationTarget
Target recipient of an invitation (from API response)| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Delivery channel: “email”, “phone”, “share”, or “internal” |
value | string | ✓ | Target address: email, phone number with country code, or share link ID |
name | string | Display name of the recipient | |
avatarUrl | string | Avatar URL for the recipient | |
status | string | Delivery status for this specific target |
InvitationScope
Scope/group that the invitation grants access to (from API response)| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Vortex internal UUID for this scope record |
accountId | string | ✓ | Your Vortex account ID |
groupId | string | ✓ | Your internal scope/group identifier |
type | string | ✓ | Scope type (e.g., “team”, “organization”, “workspace”) |
name | string | ✓ | Display name for the scope |
createdAt | string | ✓ | ISO 8601 timestamp when the scope was created |
InvitationAcceptance
Details about an invitation acceptance event| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this acceptance record |
invitationId | string | ✓ | ID of the invitation that was accepted |
email | string | Email of the user who accepted | |
phone | string | Phone of the user who accepted | |
name | string | Name of the user who accepted | |
isExisting | bool | Whether the user already had an account | |
createdAt | string | ✓ | ISO 8601 timestamp when the acceptance occurred |
Inviter
Information about the user who sent an invitation| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Your internal user ID for the inviter |
email | string | Email address of the inviter | |
name | string | Display name of the inviter | |
avatarUrl | string | Avatar URL of the inviter |
AutojoinDomain
Autojoin domain configuration - users with matching email domains automatically join| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this autojoin configuration |
domain | string | ✓ | Email domain that triggers autojoin (e.g., “acme.com”) |
AutojoinDomainsResponse
Response from getAutojoinDomains()| Field | Type | Required | Description |
|---|---|---|---|
domains | AutojoinDomain[] | ✓ | List of configured autojoin domains |
SyncInternalInvitationResponse
Response from syncInternalInvitation()| Field | Type | Required | Description |
|---|---|---|---|
invitation | InvitationResult | ✓ | The created or updated invitation |
created | bool | ✓ | True if a new invitation was created, false if existing was updated |
VortexWebhookEvent
Webhook event payload delivered to your endpoint| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this webhook delivery |
type | string | ✓ | Event type (e.g., “invitation.accepted”, “member.created”) |
timestamp | string | ✓ | ISO 8601 timestamp when the event occurred |
data | array | ✓ | Event-specific payload data |
Webhooks
Webhooks let your server receive real-time notifications when events happen in Vortex. Use them to sync invitation state with your database, trigger onboarding flows, update your CRM, or send internal notifications.Setup
- Go to your Vortex dashboard → Integrations → Webhooks tab
- Click “Add Webhook”
- Enter your endpoint URL (must be HTTPS in production)
- Copy the signing secret — you’ll use this to verify webhook signatures
- Select which events you want to receive
Example
Laravel webhook handlerEvents
| Event | Description |
|---|---|
invitation.created | A new invitation was created |
invitation.accepted | An invitation was accepted by the recipient |
invitation.deactivated | An invitation was deactivated (revoked or expired) |
invitation.email.delivered | Invitation email was successfully delivered |
invitation.email.bounced | Invitation email bounced (invalid address) |
invitation.email.opened | Recipient opened the invitation email |
invitation.link.clicked | Recipient clicked the invitation link |
invitation.reminder.sent | A reminder email was sent for a pending invitation |
member.created | A new member was created from an accepted invitation |
group.member.added | A member was added to a scope/group |
deployment.created | A new deployment configuration was created |
deployment.deactivated | A deployment was deactivated |
abtest.started | An A/B test was started |
abtest.winner_declared | An A/B test winner was declared |
email.complained | Recipient marked the email as spam |
Use Cases
- Activate users on acceptance — When invitation.accepted fires, mark the user as active in your database and trigger your onboarding flow.
- Track invitation performance — Monitor email.delivered, email.opened, and link.clicked events to measure invitation funnel metrics.
- Sync team membership — Use member.created and group.member.added to keep your internal membership records in sync.
- Alert on delivery issues — Watch for email.bounced events to proactively reach out via alternative channels.
Error Handling
| Error | Description |
|---|---|
VortexWebhookSignatureException | Thrown when webhook signature verification fails. Check that you are using the raw request body and the correct signing secret. |
Exception | Thrown for validation errors (e.g., missing API key, invalid parameters) |