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()
GenerateToken creates a signed JWT token for use with Vortex components.
This method generates a signed JWT token containing your payload data.
The token can be passed to widgets via the token prop to authenticate
and authorize the request.
Parameters:
- payload: Data to sign (user, component, scope, vars, etc.) At minimum, include user.ID for secure invitation attribution.
- options: Optional configuration. Supports ExpiresIn (default: 30 days).
- Signed JWT token string
- error if API key format is invalid or token generation fails
| Name | Type | Required | Description |
|---|---|---|---|
payload | *GenerateTokenPayload | ✓ | |
options | *GenerateTokenOptions | ✓ |
(string, error)
Example
Example
GetInvitation()
GetInvitation retrieves a specific invitation by ID
| Name | Type | Required | Description |
|---|---|---|---|
invitationID | string | ✓ |
(*InvitationResult, error)
AcceptInvitation()
AcceptInvitation accepts a single invitation (recommended method)
This is the recommended method for accepting invitations.
Parameters:
- invitationID: Single invitation ID to accept
- user: User object with email and/or phone
- *InvitationResult: The accepted invitation result
- error: Any error that occurred
| Name | Type | Required | Description |
|---|---|---|---|
invitationID | string | ✓ | |
user | *AcceptUser | ✓ |
(*InvitationResult, error)
Example
Example
Additional Methods
Additional Methods
GenerateJWT()
| Name | Type | Required | Description |
|---|---|---|---|
user | *User | ✓ | |
extra | map[string]interface{} | ✓ | |
opts | any | ✓ |
(string, error)GetInvitationsByTarget()
GetInvitationsByTarget retrieves invitations by target type and value.| Name | Type | Required | Description |
|---|---|---|---|
targetType | string | ✓ | |
targetValue | string | ✓ |
([]InvitationResult, error)RevokeInvitation()
RevokeInvitation revokes an invitation.| Name | Type | Required | Description |
|---|---|---|---|
invitationID | string | ✓ |
errorAcceptInvitations()
AcceptInvitations accepts multiple invitations.Supports three formats:- *AcceptUser (preferred): user with email/phone/name
- InvitationTarget (deprecated): single target
- []InvitationTarget (deprecated): multiple targets (calls API once per target)
| Name | Type | Required | Description |
|---|---|---|---|
invitationIDs | []string | ✓ | |
userOrTarget | interface{} | ✓ |
(*InvitationResult, error)DeleteInvitationsByGroup()
Deprecated: Use DeleteInvitationsByScope instead| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | |
groupID | string | ✓ |
errorGetInvitationsByGroup()
Deprecated: Use GetInvitationsByScope instead| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | |
groupID | string | ✓ |
([]InvitationResult, error)DeleteInvitationsByScope()
DeleteInvitationsByScope deletes all invitations for a specific group| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | |
groupID | string | ✓ |
errorGetInvitationsByScope()
GetInvitationsByScope retrieves invitations for a specific group.| Name | Type | Required | Description |
|---|---|---|---|
groupType | string | ✓ | |
groupID | string | ✓ |
([]InvitationResult, error)Reinvite()
Reinvite sends a reinvitation for a specific invitation| Name | Type | Required | Description |
|---|---|---|---|
invitationID | string | ✓ |
(*InvitationResult, error)GetAutojoinDomains()
GetAutojoinDomains retrieves autojoin domains configured for a specific scope.Parameters:- scopeType: The type of scope (e.g., “organization”, “team”, “project”)
- scope: The scope identifier (customer’s group ID)
| Name | Type | Required | Description |
|---|---|---|---|
scopeType | string | ✓ | |
scope | string | ✓ |
(*AutojoinDomainsResponse, error)Example
Example
ConfigureAutojoin()
| Name | Type | Required | Description |
|---|---|---|---|
request | *ConfigureAutojoinRequest | ✓ |
(*AutojoinDomainsResponse, error)SyncInternalInvitation()
ConfigureAutojoin configures autojoin domains for a specific scopeThis 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 |
|---|---|---|---|
request | *SyncInternalInvitationRequest | ✓ |
(*SyncInternalInvitationResponse, error)Example
Example
Types
Type Definitions
Type Definitions
GenerateTokenPayload
GenerateTokenPayload represents the payload for token generation - used to create 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 | map[string]interface{} | Custom variables to pass to the component for template rendering | |
Extra | map[string]interface{} | Additional fields to include in token |
TokenUser
TokenUser represents user data for token generation - 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”]) | |
Extra | map[string]interface{} | Additional fields included in token |
AcceptUser
AcceptUser represents user data for accepting invitations - identifies who accepted| 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 (e.g., “+15551234567”). 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, nil=unknown. Used for conversion analytics. |
InvitationResult
InvitationResult represents a complete invitation 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 |
formSubmissionData | map[string]interface{} | Data submitted through the invitation form, including standard fields and any custom fields configured on your widget | |
configurationAttributes | map[string]interface{} | Deprecated: Use FormSubmissionData instead. Contains the same data. | |
attributes | map[string]interface{} | Custom attributes attached to this invitation | |
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” (1:1), “multi_use” (1:many), or “autojoin” |
modifiedAt | *string | ISO 8601 timestamp of last modification | |
status | string | ✓ | Current status: queued, sending, sent, delivered, accepted, shared, unfurled |
target | []InvitationTarget | List of invitation recipients with their contact info and status | |
views | int | ✓ | Number of times the invitation page was viewed |
widgetConfigurationId | string | ✓ | Widget configuration ID used for this invitation |
deploymentId | string | ✓ | Deployment ID this invitation belongs to |
groups | []InvitationScope | Scopes (teams/orgs) this invitation grants access to | |
scopes | []InvitationScope | Preferred alias for Groups | |
accepts | []InvitationAcceptance | List of acceptance records if the invitation was accepted | |
scope | *string | Primary scope identifier (e.g., “team-123”) | |
scopeType | *string | Type of the primary scope (e.g., “team”, “organization”) | |
expired | bool | ✓ | Whether this invitation has passed its expiration date |
expires | *string | ISO 8601 timestamp when this invitation expires | |
metadata | map[string]interface{} | Custom metadata attached to this invitation | |
passThrough | *string | Pass-through data returned unchanged in webhooks and callbacks | |
source | *string | Source identifier for tracking (e.g., “ios-app”, “web-dashboard”) | |
subtype | *string | Subtype for analytics segmentation (e.g., “pymk”, “find-friends”) | |
creatorName | *string | Display name of the user who created this invitation | |
creatorAvatarUrl | *string | Avatar URL of the user who created this invitation |
InvitationTarget
InvitationTarget represents the target recipient of an invitation| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Delivery channel: “email”, “phone”, “share” (link), or “internal” (in-app) |
value | string | ✓ | Target address: email, phone number with country code, or share link ID |
name | *string | Display name of the recipient (e.g., “John Doe”) | |
avatarUrl | *string | Avatar URL for the recipient, shown in invitation lists and widgets |
InvitationScope
InvitationScope represents a scope/group the invitation grants access to| 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 |
scopeId | string | ✓ | Preferred alias for Scope (same value as groupId) |
type | string | ✓ | Scope type (e.g., “team”, “organization”, “workspace”) |
name | string | ✓ | Display name for the scope (e.g., “Engineering Team”) |
createdAt | string | ✓ | ISO 8601 timestamp when the scope was created |
AutojoinDomain
AutojoinDomain represents an autojoin domain - users with matching email domains automatically join the scope| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this autojoin configuration |
domain | string | ✓ | Email domain that triggers autojoin (e.g., “acme.com”) |
Client
Client represents a Vortex API clientGenerateJWTOptions
GenerateJWTOptions represents options for JWT generation| Field | Type | Required | Description |
|---|---|---|---|
expiresIn | interface{} | ✓ | JWT expiry: duration string (“5m”, “1h”, “7d”) or seconds as int. Default: 30 days |
GenerateTokenOptions
GenerateTokenOptions represents options for token generation| Field | Type | Required | Description |
|---|---|---|---|
expiresIn | interface{} | ✓ | Token expiry: duration string (“5m”, “1h”, “7d”) or seconds as int. Default: 30 days |
Group
Group represents a scope/group for JWT generation - defines user’s team/org membership in tokens| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Scope type (e.g., “team”, “organization”, “workspace”) |
id | *string | Legacy scope identifier. Use Scope instead. | |
groupId | *string | Your internal scope/group identifier (preferred) | |
name | string | ✓ | Display name for the scope (e.g., “Engineering Team”) |
Identifier
Identifier represents a user identifier - used in JWT generation to link user across channels| Field | Type | Required | Description |
|---|---|---|---|
type | string | ✓ | Identifier type: “email”, “phone”, “username”, or custom type |
value | string | ✓ | The identifier value (email address, phone number, etc.) |
InvitationAcceptance
InvitationAcceptance represents a record of an invitation being accepted| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this acceptance record |
accountId | string | ✓ | Your Vortex account ID |
acceptedAt | string | ✓ | ISO 8601 timestamp when the invitation was accepted |
target | InvitationTarget | ✓ | The target that accepted the invitation |
Inviter
Inviter represents information about the user creating the invitation| Field | Type | Required | Description |
|---|---|---|---|
userId | string | ✓ | Required: Your internal user ID for the inviter |
userEmail | *string | Optional: Email of the inviter | |
name | *string | Optional: Display name of the inviter (preferred) | |
avatarUrl | *string | Optional: Avatar URL of the inviter (preferred) | |
userName | *string | Deprecated: use Name instead | |
userAvatarUrl | *string | Deprecated: use AvatarUrl instead |
JWTPayload
JWTPayload represents the payload for JWT generation (legacy format) - use JWTPayloadSimple instead| Field | Type | Required | Description |
|---|---|---|---|
userId | string | ✓ | Your internal user ID (required for invitation attribution) |
identifiers | []Identifier | Legacy: List of user identifiers. Use userEmail instead. | |
groups | []Group | Legacy: List of groups/scopes. Use scope parameter instead. | |
role | *string | Legacy: User role. No longer used. |
JWTPayloadSimple
JWTPayloadSimple represents the simplified JWT payload (recommended format)| Field | Type | Required | Description |
|---|---|---|---|
userId | string | ✓ | Your internal user ID (required for invitation attribution) |
userEmail | string | ✓ | User’s email address (used for identification) |
userIsAutojoinAdmin | *bool | Whether user can manage autojoin settings for their scopes |
User
User represents user data for JWT generation - the authenticated user sending invitations| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Your internal user ID (required for invitation attribution) |
email | string | ✓ | User’s email address (used for identification and reply-to) |
name | *string | Display name shown to recipients (e.g., “John invited you”) | |
avatarUrl | *string | Avatar URL displayed in invitation emails and widgets (must be HTTPS) | |
userName | *string | Deprecated: use Name instead | |
userAvatarUrl | *string | Deprecated: use AvatarUrl instead | |
adminScopes | []string | List of scopes where user has admin privileges (e.g., [“autojoin”]) | |
allowedEmailDomains | []string | Restrict invitations to these email domains (e.g., [“acme.com”]) | |
Extra | map[string]interface{} | Additional fields included in signing |
VortexAnalyticsEvent
VortexAnalyticsEvent represents a client-side behavioral telemetry event from Vortex widgets| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this analytics event |
name | string | ✓ | Event name (e.g., “widget.opened”, “invite.sent”, “link.clicked”) |
accountId | string | ✓ | Your Vortex account ID |
organizationId | string | ✓ | Organization ID if using multi-org setup |
projectId | string | ✓ | Project ID the event belongs to |
environmentId | *string | Environment ID (production, staging, etc.) | |
deploymentId | *string | Deployment ID the event is associated with | |
widgetConfigurationId | *string | Widget configuration ID that generated this event | |
foreignUserId | *string | Your internal user ID who triggered the event | |
sessionId | *string | Client session ID for grouping related events | |
payload | map[string]interface{} | Event-specific payload data | |
platform | *string | Platform: “web”, “ios”, “android”, “react-native” | |
segmentation | *string | A/B test segmentation identifier | |
timestamp | string | ✓ | ISO 8601 timestamp when the event occurred |
VortexEvent
VortexEvent is the union type for webhook and analytics events - use IsWebhookEvent/IsAnalyticsEvent to determine type| Field | Type | Required | Description |
|---|---|---|---|
name | string | ✓ | Analytics: Event name (e.g., “widget.opened”) |
organizationId | string | ✓ | Analytics: Organization ID if using multi-org setup |
projectId | string | ✓ | Analytics: Project ID the event belongs to |
deploymentId | *string | Analytics: Deployment ID the event is associated with | |
widgetConfigurationId | *string | Analytics: Widget configuration ID | |
foreignUserId | *string | Analytics: Your internal user ID | |
sessionId | *string | Analytics: Client session ID | |
payload | map[string]interface{} | Analytics: Event-specific payload data | |
platform | *string | Analytics: Platform (“web”, “ios”, “android”) | |
segmentation | *string | Analytics: A/B test segmentation identifier |
VortexWebhookEvent
VortexWebhookEvent represents a server-side state change event from Vortex| Field | Type | Required | Description |
|---|---|---|---|
id | string | ✓ | Unique identifier for this webhook event |
type | string | ✓ | Event type (e.g., “invitation.accepted”, “member.created”) |
timestamp | string | ✓ | ISO 8601 timestamp when the event occurred |
accountId | string | ✓ | Your Vortex account ID |
environmentId | *string | Environment ID (production, staging, etc.) | |
sourceTable | string | ✓ | Internal: database table that triggered this event |
operation | string | ✓ | Database operation: “INSERT”, “UPDATE”, or “DELETE” |
data | map[string]interface{} | Event payload containing the relevant entity data |
VortexWebhookSignatureError
VortexWebhookSignatureError wraps signature verification failures with context| Field | Type | Required | Description |
|---|---|---|---|
Message | string | ✓ | Detailed error message explaining the signature verification failure |
VortexWebhooks
VortexWebhooks provides webhook verification and parsing.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
Events
| 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 |
|---|---|
VortexError | Returned for validation errors (e.g., missing API key, invalid parameters) or API failures. Wraps the underlying error with context. |