README

This package provides the Vortex PHP SDK for authentication and invitation management.

With this SDK, you can generate JWTs for use with the Vortex Widget and make API calls to the Vortex API.

Features

Invitation Delivery Types

Vortex supports multiple delivery methods for invitations:

email - Email invitations sent by Vortex (includes reminders and nudges)
phone - Phone invitations sent by the user/customer
share - Shareable invitation links for social sharing
internal - Internal invitations managed entirely by your application
- No email/SMS communication triggered by Vortex
- Target value can be any customer-defined identifier (UUID, string, number)
- Useful for in-app invitation flows where you handle the delivery
- Example use case: In-app notifications, dashboard invites, etc.

Installation

Install the SDK via Composer:

composer require teamvortexsoftware/vortex-php-sdk

Getting Started

Once you have the SDK installed, login to Vortex and create an API Key. Keep your API key safe! Vortex does not store the API key and it is not retrievable once it has been created.

Your API key is used to:

Sign JWTs for use with the Vortex Widget
Make API calls against the Vortex API

Usage

Generate a JWT for the Vortex Widget

The Vortex Widget requires a JWT to authenticate users. Here's how to generate one:

<?php

require_once 'vendor/autoload.php';

use TeamVortexSoftware\VortexSDK\VortexClient;

// Initialize the Vortex client with your API key
$vortex = new VortexClient(getenv('VORTEX_API_KEY'));

// Create user array
$user = [
    'id' => 'user-123',
    'email' => 'user@example.com',
    'userName' => 'Jane Doe',                                    // Optional: user's display name
    'userAvatarUrl' => 'https://example.com/avatars/jane.jpg',  // Optional: user's avatar URL
    'adminScopes' => ['autojoin']                            // Optional: grants autojoin admin privileges
];

// Generate JWT
$jwt = $vortex->generateJwt($user);

echo $jwt;

Create an API Endpoint to Provide JWT

Here's an example using a simple PHP endpoint:

<?php

require_once 'vendor/autoload.php';

use TeamVortexSoftware\VortexSDK\VortexClient;

header('Content-Type: application/json');

$vortex = new VortexClient(getenv('VORTEX_API_KEY'));

// Build admin scopes
$adminScopes = [];
if ($_SESSION['is_admin'] ?? false) {
    $adminScopes[] = 'autojoin';
}

// Create user array
$user = [
    'id' => $_SESSION['user_id'],
    'email' => $_SESSION['user_email'],
    'adminScopes' => $adminScopes
];

$jwt = $vortex->generateJwt($user);

echo json_encode(['jwt' => $jwt]);

Use with Laravel

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use TeamVortexSoftware\VortexSDK\VortexClient;

class VortexController extends Controller
{
    public function getJwt(Request $request)
    {
        $vortex = new VortexClient(config('services.vortex.api_key'));

        $user = $request->user();

        // Build admin scopes
        $adminScopes = [];
        if ($user->is_admin) {
            $adminScopes[] = 'autojoin';
        }

        // Create user array
        $vortexUser = [
            'id' => (string)$user->id,
            'email' => $user->email,
            'adminScopes' => $adminScopes
        ];

        $jwt = $vortex->generateJwt($vortexUser);

        return response()->json(['jwt' => $jwt]);
    }
}

Use with WordPress

<?php

// In your theme's functions.php or a custom plugin

use TeamVortexSoftware\VortexSDK\VortexClient;

add_action('rest_api_init', function () {
    register_rest_route('vortex/v1', '/jwt', [
        'methods' => 'POST',
        'callback' => function () {
            $vortex = new VortexClient(get_option('vortex_api_key'));

            $currentUser = wp_get_current_user();

            // Build admin scopes
            $adminScopes = [];
            if (user_can($currentUser, 'manage_options')) {
                $adminScopes[] = 'autojoin';
            }

            // Create user array
            $user = [
                'id' => (string)$currentUser->ID,
                'email' => $currentUser->user_email,
                'adminScopes' => $adminScopes
            ];

            $jwt = $vortex->generateJwt($user);

            return ['jwt' => $jwt];
        },
        'permission_callback' => function () {
            return is_user_logged_in();
        }
    ]);
});

API Methods

Invitation Management

Get Invitations by Target

$invitations = $vortex->getInvitationsByTarget('email', 'user@example.com');

Get Invitation by ID

$invitation = $vortex->getInvitation('invitation-id');

Revoke Invitation

$vortex->revokeInvitation('invitation-id');

Accept an Invitation

$result = $vortex->acceptInvitation(
    'invitation-id',
    ['email' => 'user@example.com']
);

Get Invitations by Group

$invitations = $vortex->getInvitationsByGroup('workspace', 'workspace-123');

Delete Invitations by Group

$vortex->deleteInvitationsByGroup('workspace', 'workspace-123');

Reinvite

$result = $vortex->reinvite('invitation-id');

Sync Internal Invitation

If you're using internal delivery type invitations and managing the invitation flow within your own application, you can sync invitation decisions back to Vortex when users accept or decline invitations in your system.

// Sync an internal invitation action (accept or decline)
$result = $vortex->syncInternalInvitation(
    "user-123",           // creatorId - The inviter's user ID in your system
    "user-456",           // targetValue - The invitee's user ID in your system
    "accepted",           // action - "accepted" or "declined"
    "component-uuid"      // componentId - The widget component UUID
);

echo "Processed: " . $result['processed'] . "\n";
echo "Invitation IDs: " . implode(", ", $result['invitationIds']) . "\n";

Parameters:

creatorId (string) — The inviter's user ID in your system
targetValue (string) — The invitee's user ID in your system
action ("accepted" | "declined") — The invitation decision
componentId (string) — The widget component UUID

Response:

processed (int) — Count of invitations processed
invitationIds (string[]) — IDs of processed invitations

Use cases:

You handle invitation delivery through your own in-app notifications or UI
Users accept/decline invitations within your application
You need to keep Vortex updated with the invitation status

Requirements

PHP 8.0 or higher
json extension (typically enabled by default)

License

MIT

Webhooks

The SDK provides built-in support for verifying and parsing incoming webhook events from Vortex.

use TeamVortexSoftware\VortexSDK\VortexWebhooks;
use TeamVortexSoftware\VortexSDK\VortexWebhookSignatureException;
use TeamVortexSoftware\VortexSDK\WebhookEventType;

$webhooks = new VortexWebhooks(getenv('VORTEX_WEBHOOK_SECRET'));

// In your HTTP handler (Laravel example):
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_VORTEX_SIGNATURE'] ?? '';

try {
    $event = $webhooks->constructEvent($payload, $signature);

    if (VortexWebhooks::isWebhookEvent($event)) {
        if ($event['type'] === WebhookEventType::INVITATION_ACCEPTED) {
            // Handle invitation accepted
        }
    } elseif (VortexWebhooks::isAnalyticsEvent($event)) {
        error_log("Analytics: " . $event['name']);
    }

    http_response_code(200);
    echo 'OK';
} catch (VortexWebhookSignatureException $e) {
    http_response_code(400);
    echo 'Invalid signature';
}

Support

For support, please contact support@vortexsoftware.com or visit our documentation.

teamvortexsoftware / vortex-php-sdk

Maintainers

Package info

Statistics

Security