Ruby SDK - Vortex

Vortex handles the complete invitation lifecycle — sending invites via email/SMS/share links, tracking clicks and conversions, managing referral programs, and optimizing your invitation flows with A/B testing.

Installation

gem install vortex-ruby-sdk

Quick Start

Generate a secure token for Vortex components

require 'vortex'

client = Vortex::Client.new(ENV['VORTEX_API_KEY'])

# Generate a token for the current user
token = client.generate_token(user: { id: 'user-123', email: 'user@example.com' })

# Pass the token to your frontend component

Integration 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.

Install the backend SDK

Add this SDK to your Ruby project

gem 'vortex-ruby-sdk'

Initialize the client

Create a Vortex client with your API key (keep this on the server!)

require 'vortex'

client = Vortex::Client.new(ENV['VORTEX_API_KEY'])

Generate a token for the current user

When a user loads a page with a Vortex component, generate a signed token on your server

token = client.generate_token(user: { id: current_user.id })

Pass the token to your frontend

Include the token in your page response or API response

render json: { vortex_token: token }

Render a Vortex component with the token

Use the React/Angular/Web Component with the token

import { VortexInvite } from "@teamvortexsoftware/vortex-react";

<VortexInvite token={vortexToken} />

Vortex handles the rest

The component securely communicates with Vortex servers, displays the invitation UI, sends emails/SMS, tracks conversions, and reports analytics

Methods

Core Methods

`generate_token()`

Generate a signed token for use with Vortex widgets. 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.

generate_token(payload, options = nil)

Parameters:

Name	Type	Required	Description
`payload`	`Hash`	✓	Data to sign (user, component, scope, vars, etc.)
`options`	`Hash`	✓	Optional configuration

Returns: String — Signed JWT token

Example

#   token = client.generate_token({ user: { id: 'user-123' } })
    #
    #   token = client.generate_token({
    #     component: 'widget-abc',
    #     user: { id: 'user-123', name: 'Peter', email: 'peter@example.com' },
    #     scope: 'workspace_456',
    #     vars: { company_name: 'Acme' }
    #   })
    #
    #   token = client.generate_token(payload, { expires_in: '1h' })
    #   token = client.generate_token(payload, { expires_in: 3600 }) # seconds

`get_invitation()`

Get a specific invitation by ID

get_invitation(invitation_id)

Parameters:

Name	Type	Required	Description
`invitation_id`	`String`	✓	The invitation ID

Returns: String — The invitation data

`accept_invitation()`

Accept a single invitation (recommended method) This is the recommended method for accepting invitations.

accept_invitation(invitation_id, user)

Parameters:

Name	Type	Required	Description
`invitation_id`	`String`	✓	Single invitation ID to accept
`user`	`Hash`	✓	User hash with :email and/or :phone

Returns: String — The accepted invitation result

Example

#   user = { email: 'user@example.com', name: 'John Doe' }
    #   result = client.accept_invitation('inv-123', user)

Additional Methods

`get_invitations_by_target()`

Get invitations by target

get_invitations_by_target(target_type, target_value)

Parameters:

Name	Type	Required	Description
`target_type`	`String`	✓	Type of target (email, sms)
`target_value`	`String`	✓	Value of target (email address, phone number)

Returns: String — List of invitations

`revoke_invitation()`

Revoke (delete) an invitation

revoke_invitation(invitation_id)

Parameters:

Name	Type	Required	Description
`invitation_id`	`String`	✓	The invitation ID to revoke

Returns: String — Success response

`accept_invitations()`

Accept invitations using the new User format (preferred) Supports three formats: 1. User hash (preferred): { email: ’…’, phone: ’…’, name: ’…’ } 2. Target hash (deprecated): { type: ‘email’, value: ’…’ } 3. Array of targets (deprecated): [{ type: ‘email’, value: ’…’ }, …]

accept_invitations(invitation_ids, user_or_target)

Parameters:

Name	Type	Required	Description
`invitation_ids`	`Array<String>`	✓	List of invitation IDs to accept
`user_or_target`	`Hash, Array`	✓	User hash with :email/:phone/:name keys, OR legacy target(s)

Returns: String — The accepted invitation result

Example

#   user = { email: 'user@example.com', name: 'John Doe' }
    #   result = client.accept_invitations(['inv-123'], user)
    #
    #   target = { type: 'email', value: 'user@example.com' }
    #   result = client.accept_invitations(['inv-123'], target)

`get_invitations_by_scope()`

Get invitations by group

get_invitations_by_scope(scope_type, scope)

Parameters:

Name	Type	Required	Description
`scope_type`	`String`	✓	The group type
`scope`	`String`	✓	The group ID

Returns: String — List of invitations for the group

`delete_invitations_by_scope()`

Delete invitations by group

delete_invitations_by_scope(scope_type, scope)

Parameters:

Name	Type	Required	Description
`scope_type`	`String`	✓	The group type
`scope`	`String`	✓	The group ID

Returns: String — Success response

`reinvite()`

Reinvite a user

reinvite(invitation_id)

Parameters:

Name	Type	Required	Description
`invitation_id`	`String`	✓	The invitation ID to reinvite

Returns: String — The reinvited invitation result

`get_autojoin_domains()`

Get autojoin domains configured for a specific scope

get_autojoin_domains(scope_type, scope)

Parameters:

Name	Type	Required	Description
`scope_type`	`String`	✓	The type of scope (e.g., “organization”, “team”, “project”)
`scope`	`String`	✓	The scope identifier (customer’s group ID)

Returns: String — Response with :autojoin_domains array and :invitation

Example

#   result = client.get_autojoin_domains('organization', 'acme-org')
    #   result['autojoinDomains'].each do |domain|
    #     puts "Domain: #{domain['domain']}"
    #   end

`configure_autojoin()`

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).

configure_autojoin(scope, scope_type, domains, component_id, scope_name = nil, metadata = nil)

Parameters:

Name	Type	Required	Description
`scope`	`String`	✓	The scope identifier (customer’s group ID)
`scope_type`	`String`	✓	The type of scope (e.g., “organization”, “team”)
`domains`	`Array<String>`	✓	Array of domains to configure for autojoin
`component_id`	`String`	✓	The component ID
`scope_name`	`String, nil`	✓	Optional display name for the scope
`metadata`	`Hash, nil`	✓	Optional metadata to attach to the invitation

Returns: String — Response with :autojoin_domains array and :invitation

Example

#   result = client.configure_autojoin(
    #     'acme-org',
    #     'organization',
    #     ['acme.com', 'acme.org'],
    #     'component-123',
    #     'Acme Corporation'
    #   )

Types

Type Definitions

`GenerateTokenPayload`

Payload for generate_token() - used to generate secure tokens for Vortex components

Field	Type	Description
`user`	`Hash (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`	`Hash`	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”)
`avatar_url`	`String`		URL to user’s avatar image. Displayed in invitation emails and widgets.
`admin_scopes`	`Array<String>`		List of scope IDs where this user has admin privileges
`allowed_email_domains`	`Array<String>`		Restrict invitations to specific email domains (e.g., [“acme.com”])

`AcceptUser`

User data for accepting invitations - identifies who accepted the invitation

Field	Type	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)
`is_existing`	`Boolean`	Whether user was already registered. true=existing, false=new signup, nil=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”)
`group_id`	`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
`scope_type`	`String`	✓	Type of scope (e.g., “team”, “workspace”)
`scope_id`	`String`	✓	Your internal identifier for the scope
`domains`	`Array<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
`inviter_id`	`String`	✓	Your internal user ID for the person who sent the invitation
`target`	`Hash (CreateInvitationTarget)`	✓	The invitation recipient
`scopes`	`Array<Hash>`		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
`account_id`	`String`	✓	Your Vortex account ID
`click_throughs`	`Integer`	✓	Number of times the invitation link was clicked
`form_submission_data`	`Hash	nil`		Invitation form data submitted by the user, including invitee identifiers (such as email addresses, phone numbers, or internal IDs) and the values of any custom fields.
`configuration_attributes`	`Hash	nil`		Deprecated: Use form_submission_data instead. Contains the same data.
`created_at`	`String`	✓	ISO 8601 timestamp when the invitation was created
`deactivated`	`Boolean`	✓	Whether this invitation has been revoked or expired
`delivery_count`	`Integer`	✓	Number of times the invitation was sent (including reminders)
`delivery_types`	`Array<String>`	✓	Channels used to deliver: “email”, “phone”, “share”, “internal”
`foreign_creator_id`	`String`	✓	Your internal user ID for the person who created this invitation
`invitation_type`	`String`	✓	Type: “single_use”, “multi_use”, or “autojoin”
`status`	`String`	✓	Current status: queued, sending, sent, delivered, accepted, shared
`target`	`Array<Hash>`	✓	List of invitation recipients with their contact info and status
`views`	`Integer`	✓	Number of times the invitation page was viewed
`groups`	`Array<Hash>`	✓	Scopes (teams/orgs) this invitation grants access to
`expired`	`Boolean`	✓	Whether this invitation has passed its expiration date
`expires`	`String`		ISO 8601 timestamp when this invitation expires
`inviter`	`Hash (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
`avatar_url`	`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
`account_id`	`String`	✓	Your Vortex account ID
`group_id`	`String`	✓	Your internal scope/group identifier
`type`	`String`	✓	Scope type (e.g., “team”, “organization”, “workspace”)
`name`	`String`	✓	Display name for the scope
`created_at`	`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
`invitation_id`	`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
`is_existing`	`Boolean`		Whether the user already had an account
`created_at`	`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
`avatar_url`	`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 get_autojoin_domains()

Field	Type	Required	Description
`domains`	`Array<AutojoinDomain>`	✓	List of configured autojoin domains

`SyncInternalInvitationResponse`

Response from sync_internal_invitation()

Field	Type	Required	Description
`invitation`	`Hash (InvitationResult)`	✓	The created or updated invitation
`created`	`Boolean`	✓	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`	`Hash`	✓	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

Rails webhook handler

class WebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def vortex
    webhooks = Vortex::Webhooks.new(ENV['VORTEX_WEBHOOK_SECRET'])
    
    payload = request.raw_post
    signature = request.headers['X-Vortex-Signature']
    
    # Verify the signature
    unless webhooks.verify_signature(payload, signature)
      return render json: { error: 'Invalid signature' }, status: 400
    end
    
    # Parse the event
    event = webhooks.parse_event(payload)
    
    case event['type']
    when 'invitation.accepted'
      # User accepted an invitation — activate their account
      Rails.logger.info "Accepted: #{event['data']}"
    when 'member.created'
      # New member joined via invitation
      Rails.logger.info "New member: #{event['data']}"
    end
    
    render json: { received: true }
  end
end

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`	Raised for validation errors (e.g., missing API key, invalid parameters) or API failures

SDK Reference

Documentation Index

​Installation

​Quick Start

​Integration Flow

​Methods

​Core Methods

​generate_token()

​get_invitation()

​accept_invitation()

​get_invitations_by_target()

​revoke_invitation()

​accept_invitations()

​get_invitations_by_scope()

​delete_invitations_by_scope()

​reinvite()

​get_autojoin_domains()

​configure_autojoin()

​Types

​GenerateTokenPayload

​TokenUser

​AcceptUser

​CreateInvitationTarget

​CreateInvitationScope

​Identifier

​ConfigureAutojoinRequest

​SyncInternalInvitationRequest

​InvitationResult

​InvitationTarget

​InvitationScope

​InvitationAcceptance

​Inviter

​AutojoinDomain

​AutojoinDomainsResponse

​SyncInternalInvitationResponse

​VortexWebhookEvent

​Webhooks

​Setup

​Example

​Events

​Use Cases

​Error Handling

​Resources

Installation

Quick Start

Integration Flow

Methods

Core Methods

`generate_token()`

`get_invitation()`

`accept_invitation()`

`get_invitations_by_target()`

`revoke_invitation()`

`accept_invitations()`

`get_invitations_by_scope()`

`delete_invitations_by_scope()`

`reinvite()`

`get_autojoin_domains()`

`configure_autojoin()`

Types

`GenerateTokenPayload`

`TokenUser`

`AcceptUser`

`CreateInvitationTarget`

`CreateInvitationScope`

`Identifier`

`ConfigureAutojoinRequest`

`SyncInternalInvitationRequest`

`InvitationResult`

`InvitationTarget`

`InvitationScope`

`InvitationAcceptance`

`Inviter`

`AutojoinDomain`

`AutojoinDomainsResponse`

`SyncInternalInvitationResponse`

`VortexWebhookEvent`

Webhooks

Setup

Example

Events

Use Cases

Error Handling

Resources