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.

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',
    'adminScopes' => ['autojoin']  // Optional - included as adminScopes array in JWT
];

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

echo $jwt;

Generate JWT with Additional Properties

<?php

require_once 'vendor/autoload.php';

use TeamVortexSoftware\VortexSDK\VortexClient;

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

// User without admin scopes
$user = [
    'id' => 'user-123',
    'email' => 'user@example.com'
];

// Additional properties
$extra = [
    'role' => 'admin',
    'department' => 'Engineering'
];

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

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 Invitations

$result = $vortex->acceptInvitations(
    ['invitation-id-1', 'invitation-id-2'],
    ['type' => 'email', 'value' => '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');

Requirements

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

License

MIT

Support

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

teamvortexsoftware / vortex-php-sdk

Maintainers

Details