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
generate_token()
Generate a signed token for use with Vortex widgets
| Name | Type | Required | Description |
|---|---|---|---|
payload | &GenerateTokenPayload | ✓ | Data to sign (user, component, scope, vars, etc.) |
options | Option<&GenerateTokenOptions> | Optional configuration (expires_in) |
Result<String, VortexError>
get_invitation()
Get a specific invitation by ID
| Name | Type | Required | Description |
|---|---|---|---|
invitation_id | &str | ✓ | The invitation ID |
Result<Invitation, VortexError>
accept_invitation()
Accept a single invitation (recommended method)
| Name | Type | Required | Description |
|---|---|---|---|
invitation_id | &str | ✓ | Single invitation ID to accept |
user | crate::types::AcceptUser | ✓ | User object with email and/or phone |
Result<Invitation, VortexError>
Example
Example
Additional Methods
Additional Methods
get_invitations_by_target()
Get invitations by target (email or sms)| Name | Type | Required | Description |
|---|---|---|---|
target_type | &str | ✓ | Type of target (email, phone) |
target_value | &str | ✓ | The target value |
Result<Vec<Invitation>, VortexError>revoke_invitation()
Revoke (delete) an invitation| Name | Type | Required | Description |
|---|---|---|---|
invitation_id | &str | ✓ | The invitation ID to revoke |
Result<(), VortexError>accept_invitations()
Accept multiple invitations| Name | Type | Required | Description |
|---|---|---|---|
invitation_ids | Vec<String> | ✓ | Vector of invitation IDs to accept |
param | impl Into<crate::types::AcceptInvitationParam> | ✓ | User data (preferred) or legacy target format |
Result<Invitation, VortexError>delete_invitations_by_scope()
Delete all invitations for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
scope_type | &str | ✓ | The scope type (organization, team, etc.) |
scope | &str | ✓ | The scope identifier |
Result<(), VortexError>get_invitations_by_scope()
Get all invitations for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
scope_type | &str | ✓ | The scope type (organization, team, etc.) |
scope | &str | ✓ | The scope identifier |
Result<Vec<Invitation>, VortexError>reinvite()
Reinvite a user (send invitation again)| Name | Type | Required | Description |
|---|---|---|---|
invitation_id | &str | ✓ | The invitation ID to reinvite |
Result<Invitation, VortexError>create_invitation()
Create an invitation from your backend This method allows you to create invitations programmatically using your API key, without requiring a user JWT token. Useful for server-side invitation creation, such as “People You May Know” flows or admin-initiated invitations. - email: Send an email invitation - sms: Create an SMS invitation (short link returned for you to send) - internal: Create an internal invitation for PYMK flows (no email sent)| Name | Type | Required | Description |
|---|---|---|---|
request | CreateInvitationRequest | ✓ |
Result<CreateInvitationResponse, VortexError>Example
Example
get_autojoin_domains()
Get autojoin domains configured for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
scope_type | &str | ✓ | The type of scope (e.g., “organization”, “team”, “project”) |
scope | &str | ✓ | The scope identifier (customer’s group ID) |
Result<AutojoinDomainsResponse, VortexError>sync_internal_invitation()
Configure autojoin domains for a specific scope| Name | Type | Required | Description |
|---|---|---|---|
request | &SyncInternalInvitationRequest | ✓ | The configure autojoin request |
Result<SyncInternalInvitationResponse, VortexError>Example
Example
Types
Type Definitions
Type Definitions
GenerateTokenPayload
Payload for generate_token() - used to generate secure tokens for Vortex components| Field | Type | Required | Description |
|---|---|---|---|
user | Option<TokenUser> | The authenticated user who will be using the Vortex component | |
component | Option<String> | Component ID to generate token for (from your Vortex dashboard) | |
scope | Option<String> | Scope identifier to restrict invitations (format: “scopeType:scopeId”) | |
vars | Option<HashMap<String, Value>> | 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 | Option<String> | User’s email address. Used for reply-to in invitation emails. | |
name | Option<String> | Display name shown to invitation recipients (e.g., “John invited you”) | |
avatar_url | Option<String> | URL to user’s avatar image. Displayed in invitation emails and widgets. | |
admin_scopes | Option<Vec<String>> | List of scope IDs where this user has admin privileges | |
allowed_email_domains | Option<Vec<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 | Option<String> | Email address of the accepting user. At least one of email or phone is required. | |
phone | Option<String> | Phone number with country code. At least one of email or phone is required. | |
name | Option<String> | Display name of the accepting user (shown in notifications to inviter) | |
is_existing | Option<bool> | Whether user was already registered. Some(true)=existing, Some(false)=new signup, None=unknown. |
CreateInvitationTarget
Target specification when creating an invitation - where to send the invite| Field | Type | Required | Description |
|---|---|---|---|
target_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 | Option<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 |
|---|---|---|---|
scope_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 |
|---|---|---|---|
identifier_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 | Vec<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 | CreateInvitationTarget | ✓ | The invitation recipient |
scopes | Option<Vec<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 |
account_id | String | ✓ | Your Vortex account ID |
click_throughs | i32 | ✓ | Number of times the invitation link was clicked |
created_at | String | ✓ | ISO 8601 timestamp when the invitation was created |
deactivated | bool | ✓ | Whether this invitation has been revoked or expired |
delivery_count | i32 | ✓ | Number of times the invitation was sent (including reminders) |
delivery_types | Vec<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 | Vec<InvitationTarget> | ✓ | List of invitation recipients with their contact info and status |
views | i32 | ✓ | Number of times the invitation page was viewed |
groups | Vec<InvitationScope> | ✓ | Scopes (teams/orgs) this invitation grants access to |
expired | bool | ✓ | Whether this invitation has passed its expiration date |
expires | Option<String> | ISO 8601 timestamp when this invitation expires | |
inviter | Option<Inviter> | Information about who sent the invitation |
InvitationTarget
Target recipient of an invitation (from API response)| Field | Type | Required | Description |
|---|---|---|---|
target_type | String | ✓ | Delivery channel: “email”, “phone”, “share”, or “internal” |
value | String | ✓ | Target address: email, phone number with country code, or share link ID |
name | Option<String> | Display name of the recipient | |
avatar_url | Option<String> | Avatar URL for the recipient | |
status | Option<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 |
scope_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 | Option<String> | Email of the user who accepted | |
phone | Option<String> | Phone of the user who accepted | |
name | Option<String> | Name of the user who accepted | |
is_existing | Option<bool> | 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 | Option<String> | Email address of the inviter | |
name | Option<String> | Display name of the inviter | |
avatar_url | Option<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 | Vec<AutojoinDomain> | ✓ | List of configured autojoin domains |
SyncInternalInvitationResponse
Response from sync_internal_invitation()| 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 |
event_type | String | ✓ | Event type (e.g., “invitation.accepted”, “member.created”) |
timestamp | String | ✓ | ISO 8601 timestamp when the event occurred |
data | Value | ✓ | Event-specific payload data (serde_json::Value) |
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
Axum 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 |
|---|---|
VortexError::WebhookSignatureInvalid | Returned when webhook signature verification fails. Check that you are using the raw request body and the correct signing secret. |
VortexError | General error type for validation errors (e.g., missing API key, invalid parameters) |