vortex-python-sdk 0.19.0.dev20260427233757

Vortex Python SDK for invitation management and JWT generation

vortex-python-sdk

Invitation infrastructure for modern apps

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. You focus on your product; Vortex handles the growth mechanics. Learn more about Vortex →

Why This SDK?

This backend SDK securely signs user data for Vortex components. Your API key stays on your server, while the signed token is passed to the frontend where Vortex components render the invitation UI.

• Keep your API key secure — it never touches the browser
• Sign user identity for attribution — know who sent each invitation
• Control what data components can access via scoped tokens
• Verify webhook signatures for secure event handling

How It Works

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.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Server   │     │  User Browser   │     │  Vortex Cloud   │
│    (this SDK)   │     │   (component)   │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │  1. generate_token()  │                       │
         │◄──────────────────────│                       │
         │                       │                       │
         │  2. Return token      │                       │
         │──────────────────────►│                       │
         │                       │                       │
         │                       │  3. Component calls   │
         │                       │     API with token    │
         │                       │──────────────────────►│
         │                       │                       │
         │                       │  4. Render UI,        │
         │                       │     send invitations  │
         │                       │◄──────────────────────│
         │                       │                       │

Integration Flow

1. Install the backend SDK [backend]

Add this SDK to your Python project

pip install vortex-python-sdk

2. Initialize the client [backend]

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

from vortex_sdk import Vortex

vortex = Vortex(api_key=os.environ["VORTEX_API_KEY"])

3. Generate a token for the current user [backend]

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

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

4. Pass the token to your frontend [backend]

Include the token in your page response or API response

return {"vortex_token": token}

5. Render a Vortex component with the token [frontend]

Use the React/Angular/Web Component with the token

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

<VortexInvite token={vortexToken} />

6. Vortex handles the rest [vortex]

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

Security Model

⚠️ Important: Your Vortex API key is a secret that grants full access to your account. It must never be exposed to browsers or client-side code.

By signing tokens on your server, you:

• Keep your API key secret (it never leaves your server)
• Control exactly what user data is shared with components
• Ensure invitations are attributed to real, authenticated users
• Prevent abuse — users can only send invitations as themselves

When Signing is Optional

Token signing is controlled by your component configuration in the Vortex dashboard. If "Require Secure Token" is enabled, requests without a valid token will be rejected. If disabled (e.g., for public referral programs), components work without backend signing. The SDK is still useful for server-side operations like verifying webhooks regardless of this setting.

---

Quick Start

Generate a secure token for Vortex components

from vortex_sdk import Vortex

vortex = Vortex(api_key=os.environ["VORTEX_API_KEY"])

# Generate a token for the current user
token = vortex.generate_token(user={"id": "user-123", "email": "[e-mail]"})

# Pass the token to your frontend component
# <VortexInvite token={token} />

Installation

pip install vortex-python-sdk

Other package managers

poetry:

poetry add vortex-python-sdk

pipenv:

pipenv install vortex-python-sdk

Initialization

vortex = Vortex(api_key=os.environ["VORTEX_API_KEY"])

Environment Variables

Variable	Required	Description
VORTEX_API_KEY	✓	Your Vortex API key

Core Methods

These are the methods you'll use most often.

generate_token()

Generate a signed 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.

Signature:

generate_token(payload: GenerateTokenPayload | dict[str, Any], options: GenerateTokenOptions | dict[str, Any] | NoneType = None) -> str

Parameters:

Name	Type	Required	Description
payload	GenerateTokenPayload | dict[str, Any]	✓	Data to sign (user, component, scope, vars, etc.) At minimum, include user.id for secure invitation attribution.
options	GenerateTokenOptions | dict[str, Any] | NoneType		Optional configuration. Supports expires_in (default: 30 days).

Returns: str — Signed JWT token string

Added in v0.8.0

---

get_invitation()

Get a specific invitation by ID

Signature:

get_invitation(invitation_id: str) -> InvitationResult

Parameters:

Name	Type	Required	Description
invitation_id	str	✓	Invitation ID

Returns: InvitationResult — Invitation object

Added in v0.1.0

---

accept_invitation()

Accept a single invitation (recommended method)

This is the recommended method for accepting invitations.

Signature:

accept_invitation(invitation_id: str, user: AcceptUser | dict[str, Any]) -> dict

Parameters:

Name	Type	Required	Description
invitation_id	str	✓	Single invitation ID to accept
user	AcceptUser | dict[str, Any]	✓	User object with email/phone/name

Returns: dict — API response

Added in v0.6.0

---

All Methods

Click to expand full method reference

get_invitations_by_target()

Get invitations for a specific target

Signature:

get_invitations_by_target(target_type: Literal[email, username, phoneNumber], target_value: str) -> list[InvitationResult]

Parameters:

Name	Type	Required	Description
target_type	Literal[email, username, phoneNumber]	✓	Type of target (email, username, or phoneNumber)
target_value	str	✓	Target value

Returns: list[InvitationResult] — List of invitations

Added in v0.1.0

---

revoke_invitation()

Revoke an invitation

Signature:

revoke_invitation(invitation_id: str) -> dict

Parameters:

Name	Type	Required	Description
invitation_id	str	✓	Invitation ID to revoke

Returns: dict — API response

Added in v0.1.0

---

accept_invitations()

Accept multiple invitations using the new User format (preferred)

Signature:

accept_invitations(invitation_ids: list[str], user_or_target: AcceptUser | InvitationTarget | dict[str, Any] | list[InvitationTarget | dict[str, str]]) -> dict

Parameters:

Name	Type	Required	Description
invitation_ids	list[str]	✓	List of invitation IDs to accept
user_or_target	AcceptUser | InvitationTarget | dict[str, Any] | list[InvitationTarget | dict[str, str]]	✓	User object with email/phone/name (preferred) OR legacy target format (deprecated)

Returns: dict — API response Example (new format): user = AcceptUser(email="[e-mail]", name="John Doe") result = await client.accept_invitations(["inv-123"], user) Example (legacy format - deprecated): target = InvitationTarget(type="email", value="[e-mail]") result = await client.accept_invitations(["inv-123"], target)

Added in v0.1.0

---

delete_invitations_by_scope()

Delete all invitations for a specific group

Signature:

delete_invitations_by_scope(scope_type: str, scope: str) -> dict

Parameters:

Name	Type	Required	Description
scope_type	str	✓	Type of group
scope	str	✓	Group ID

Returns: dict — API response

Added in v0.4.0

---

get_invitations_by_scope()

Get invitations for a specific group

Signature:

get_invitations_by_scope(scope_type: str, scope: str) -> list[InvitationResult]

Parameters:

Name	Type	Required	Description
scope_type	str	✓	Type of group
scope	str	✓	Group ID

Returns: list[InvitationResult] — List of invitations

Added in v0.4.0

---

reinvite()

Reinvite for a specific invitation

Signature:

reinvite(invitation_id: str) -> InvitationResult

Parameters:

Name	Type	Required	Description
invitation_id	str	✓	Invitation ID to reinvite

Returns: InvitationResult — Updated invitation object

Added in v0.2.0

---

get_autojoin_domains()

Get autojoin domains configured for a specific scope

Signature:

get_autojoin_domains(scope_type: str, scope: str) -> AutojoinDomainsResponse

Parameters:

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)

Returns: AutojoinDomainsResponse — AutojoinDomainsResponse with autojoin_domains and associated invitation

Added in v0.6.0

---

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

Signature:

configure_autojoin(scope: str, scope_type: str, domains: list[str], component_id: str, scope_name: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> AutojoinDomainsResponse

Parameters:

Name	Type	Required	Description
scope	str	✓	The scope identifier (customer's group ID)
scope_type	str	✓	The type of scope (e.g., "organization", "team")
domains	list[str]	✓	Array of domains to configure for autojoin
component_id	str	✓	The component ID
scope_name	Optional[str]		Optional display name for the scope
metadata	Optional[dict[str, Any]]		Optional metadata to attach to the invitation

Returns: AutojoinDomainsResponse — AutojoinDomainsResponse with updated autojoin_domains and associated invitation

Added in v0.6.0

---

Types

Click to expand type definitions

GenerateTokenPayload

Payload for generate_token() - 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	str		Component ID to generate token for (from your Vortex dashboard)
scope	str		Scope identifier to restrict invitations (format: "scopeType:scopeId")
vars	dict		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	str	✓	Unique identifier for the user in your system. Used to attribute invitations.
email	str		User's email address. Used for reply-to in invitation emails.
name	str		Display name shown to invitation recipients (e.g., "John invited you")
avatar_url	str		URL to user's avatar image. Displayed in invitation emails and widgets.
admin_scopes	List[str]		List of scope IDs where this user has admin privileges
allowed_email_domains	List[str]		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	str		Email address of the accepting user. At least one of email or phone is required.
phone	str		Phone number with country code. At least one of email or phone is required.
name	str		Display name of the accepting user (shown in notifications to inviter)
is_existing	bool		Whether user was already registered. True=existing, False=new signup, None=unknown.

CreateInvitationTarget

Target specification when creating an invitation - where to send the invite

Field	Type	Required	Description
type	str	✓	Delivery channel: "email", "phone", "share", or "internal"
value	str	✓	Target address: email address, phone number with country code, or internal user ID
name	str		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	str	✓	Scope type (e.g., "team", "organization", "workspace")
group_id	str	✓	Your internal identifier for this scope/group
name	str	✓	Display name for the scope (shown in invitation emails)

Identifier

Email or phone identifier for looking up users

Field	Type	Required	Description
type	str	✓	Identifier type: "email" or "phone"
value	str	✓	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	str	✓	Type of scope (e.g., "team", "workspace")
scope_id	str	✓	Your internal identifier for the scope
domains	List[str]	✓	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	str	✓	Your internal user ID for the person who sent the invitation
target	CreateInvitationTarget	✓	The invitation recipient
scopes	List[CreateInvitationScope]		Scopes/groups the invitation grants access to

InvitationResult

Complete invitation details as returned by the Vortex API

Field	Type	Required	Description
id	str	✓	Unique identifier for this invitation
account_id	str	✓	Your Vortex account ID
click_throughs	int	✓	Number of times the invitation link was clicked
form_submission_data	Dict[str, Any] | None		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	Dict[str, Any] | None		Deprecated: Use form_submission_data instead. Contains the same data.
created_at	str	✓	ISO 8601 timestamp when the invitation was created
deactivated	bool	✓	Whether this invitation has been revoked or expired
delivery_count	int	✓	Number of times the invitation was sent (including reminders)
delivery_types	List[str]	✓	Channels used to deliver: "email", "phone", "share", "internal"
foreign_creator_id	str	✓	Your internal user ID for the person who created this invitation
invitation_type	str	✓	Type: "single_use", "multi_use", or "autojoin"
status	str	✓	Current status: queued, sending, sent, delivered, accepted, shared
target	List[InvitationTarget]	✓	List of invitation recipients with their contact info and status
views	int	✓	Number of times the invitation page was viewed
groups	List[InvitationScope]	✓	Scopes (teams/orgs) this invitation grants access to
expired	bool	✓	Whether this invitation has passed its expiration date
expires	str		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	str	✓	Delivery channel: "email", "phone", "share", or "internal"
value	str	✓	Target address: email, phone number with country code, or share link ID
name	str		Display name of the recipient
avatar_url	str		Avatar URL for the recipient
status	str		Delivery status for this specific target

InvitationScope

Scope/group that the invitation grants access to (from API response)

Field	Type	Required	Description
id	str	✓	Vortex internal UUID for this scope record
account_id	str	✓	Your Vortex account ID
group_id	str	✓	Your internal scope/group identifier
type	str	✓	Scope type (e.g., "team", "organization", "workspace")
name	str	✓	Display name for the scope
created_at	str	✓	ISO 8601 timestamp when the scope was created

InvitationAcceptance

Details about an invitation acceptance event

Field	Type	Required	Description
id	str	✓	Unique identifier for this acceptance record
invitation_id	str	✓	ID of the invitation that was accepted
email	str		Email of the user who accepted
phone	str		Phone of the user who accepted
name	str		Name of the user who accepted
is_existing	bool		Whether the user already had an account
created_at	str	✓	ISO 8601 timestamp when the acceptance occurred

Inviter

Information about the user who sent an invitation

Field	Type	Required	Description
id	str	✓	Your internal user ID for the inviter
email	str		Email address of the inviter
name	str		Display name of the inviter
avatar_url	str		Avatar URL of the inviter

AutojoinDomain

Autojoin domain configuration - users with matching email domains automatically join

Field	Type	Required	Description
id	str	✓	Unique identifier for this autojoin configuration
domain	str	✓	Email domain that triggers autojoin (e.g., "acme.com")

AutojoinDomainsResponse

Response from get_autojoin_domains()

Field	Type	Required	Description
domains	List[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	str	✓	Unique identifier for this webhook delivery
type	str	✓	Event type (e.g., "invitation.accepted", "member.created")
timestamp	str	✓	ISO 8601 timestamp when the event occurred
data	dict	✓	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

1. Go to your Vortex dashboard → Integrations → Webhooks tab
2. Click "Add Webhook"
3. Enter your endpoint URL (must be HTTPS in production)
4. Copy the signing secret — you'll use this to verify webhook signatures
5. Select which events you want to receive

Verifying Webhooks

Always verify webhook signatures using VortexWebhooks.verify_signature() to ensure requests are from Vortex. The signature is sent in the X-Vortex-Signature header.

Example: Flask webhook handler

from flask import Flask, request, jsonify
from vortex_sdk import VortexWebhooks
import os

app = Flask(__name__)
webhooks = VortexWebhooks(os.environ["VORTEX_WEBHOOK_SECRET"])

@app.route("/webhooks/vortex", methods=["POST"])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get("X-Vortex-Signature")

    # Verify the signature
    if not webhooks.verify_signature(payload, signature):
        return jsonify({"error": "Invalid signature"}), 400

    # Parse the event
    event = webhooks.parse_event(payload)

    if event["type"] == "invitation.accepted":
        # User accepted an invitation — activate their account
        print(f"Accepted: {event['data']}")
    elif event["type"] == "member.created":
        # New member joined via invitation
        print(f"New member: {event['data']}")

    return jsonify({"received": True})

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

Supported 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

Error Handling

All SDK errors extend VortexApiError.

Error	Description
VortexWebhookSignatureError	Raised when webhook signature verification fails. Check that you are using the raw request body and the correct signing secret.
VortexApiError	Raised for validation errors (e.g., missing API key, invalid parameters)

---