Vortex Rust SDK

This crate provides the Vortex Rust 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

Add the SDK to your Cargo.toml:

[dependencies]
vortex-sdk = "1.0"
tokio = { version = "1.0", features = ["full"] }

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:

use vortex_sdk::{VortexClient, Identifier, Group};

fn main() {
    // Initialize the Vortex client with your API key
    let client = VortexClient::new(std::env::var("VORTEX_API_KEY").unwrap());

    // User ID from your system
    let user_id = "users-id-in-my-system";

    // Identifiers associated with the user
    let identifiers = vec![
        Identifier::new("email", "user@example.com"),
        Identifier::new("sms", "18008675309"),
    ];

    // Groups the user belongs to (specific to your product)
    let groups = vec![
        Group::new("workspace", "workspace-123", "My Workspace"),
        Group::new("document", "doc-456", "Project Plan"),
    ];

    // User role (if applicable)
    let role = Some("admin");

    // Generate the JWT
    let jwt = client.generate_jwt(user_id, identifiers, groups, role).unwrap();

    println!("JWT: {}", jwt);
}

Async API Usage

All API methods are async and require a tokio runtime:

use vortex_sdk::{VortexClient, Identifier, Group, InvitationTarget};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = VortexClient::new(std::env::var("VORTEX_API_KEY")?);

    // Generate a JWT
    let jwt = client.generate_jwt(
        "user-123",
        vec![Identifier::new("email", "user@example.com")],
        vec![Group::new("team", "team-1", "Engineering")],
        Some("admin")
    )?;

    println!("JWT: {}", jwt);

    // Get invitations by target
    let invitations = client
        .get_invitations_by_target("email", "user@example.com")
        .await?;

    println!("Found {} invitations", invitations.len());

    Ok(())
}

Using with Axum (Web Framework)

Here's an example of using the SDK with the Axum web framework:

use axum::{
    extract::State,
    http::StatusCode,
    response::Json,
    routing::get,
    Router,
};
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use vortex_sdk::{VortexClient, Identifier, Group};

#[derive(Clone)]
struct AppState {
    vortex: Arc<VortexClient>,
}

#[derive(Serialize)]
struct JwtResponse {
    jwt: String,
}

async fn get_jwt(State(state): State<AppState>) -> Result<Json<JwtResponse>, StatusCode> {
    let jwt = state
        .vortex
        .generate_jwt(
            "user-123",
            vec![Identifier::new("email", "user@example.com")],
            vec![Group::new("workspace", "ws-1", "Main Workspace")],
            Some("member"),
        )
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Json(JwtResponse { jwt }))
}

#[tokio::main]
async fn main() {
    let vortex = Arc::new(VortexClient::new(
        std::env::var("VORTEX_API_KEY").unwrap(),
    ));

    let app = Router::new()
        .route("/api/vortex-jwt", get(get_jwt))
        .with_state(AppState { vortex });

    let listener = tokio::net::TcpListener::bind("127.0.0.1:3000")
        .await
        .unwrap();

    axum::serve(listener, app).await.unwrap();
}

API Methods

All API methods are asynchronous and require the tokio runtime.

Invitation Management

Get Invitations by Target

let invitations = client
    .get_invitations_by_target("email", "user@example.com")
    .await?;

Get Invitation by ID

let invitation = client.get_invitation("invitation-id").await?;

Revoke Invitation

client.revoke_invitation("invitation-id").await?;

Accept Invitations

use vortex_sdk::InvitationTarget;

let target = InvitationTarget::new("email", "user@example.com");
let result = client
    .accept_invitations(
        vec!["invitation-id-1".to_string(), "invitation-id-2".to_string()],
        target,
    )
    .await?;

Get Invitations by Group

let invitations = client
    .get_invitations_by_group("workspace", "workspace-123")
    .await?;

Delete Invitations by Group

client
    .delete_invitations_by_group("workspace", "workspace-123")
    .await?;

Reinvite

let result = client.reinvite("invitation-id").await?;

Error Handling

The SDK uses a custom VortexError type for error handling:

use vortex_sdk::{VortexClient, VortexError};

match client.get_invitation("invalid-id").await {
    Ok(invitation) => println!("Got invitation: {:?}", invitation),
    Err(VortexError::ApiError(msg)) => eprintln!("API error: {}", msg),
    Err(VortexError::HttpError(msg)) => eprintln!("HTTP error: {}", msg),
    Err(e) => eprintln!("Other error: {}", e),
}

Requirements

• Rust 1.70 or higher
• Tokio runtime for async operations

Features

• Type-safe: Full type safety with Rust's type system
• Async/await: Built on tokio for efficient async operations
• React Compatible: JWTs generated using the same algorithm as Node.js SDK
• Comprehensive: All Vortex API endpoints supported
• Error handling: Rich error types for better debugging

License

MIT

Support

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