Crate runbeam_sdk 

Runbeam SDK

A Rust library for integrating with the Runbeam Cloud API.

This SDK provides:

• JWT token validation with RS256 and JWKS caching
• Laravel Sanctum API token support
• Runbeam Cloud API client for gateway authorization
• Secure token storage via encrypted filesystem storage (age encryption)
• Type definitions for API requests/responses and error handling

Authentication Methods

The SDK supports two authentication methods:

JWT Tokens (Legacy)

JWT tokens with RS256 signature validation. The SDK performs local validation using public keys fetched from JWKS endpoints. Use this method when you need local token validation and claim extraction.

Laravel Sanctum API Tokens

Laravel Sanctum API tokens (format: {id}|{token}) are passed directly to the server for validation. Use this method for simpler authentication flows where local token validation is not required.

Example (JWT Authentication)

use runbeam_sdk::{
    RunbeamClient,
    validate_jwt_token,
    JwtValidationOptions,
    save_machine_token,
    MachineToken,
};

// Validate a user JWT token with trusted issuers
let options = JwtValidationOptions::new()
    .with_trusted_issuers(vec!["https://api.runbeam.io".to_string()]);
let claims = validate_jwt_token("eyJhbGci...", &options).await?;

// Create API client from JWT issuer
let client = RunbeamClient::new(claims.api_base_url());

// Authorize a gateway and get machine token
let response = client.authorize_gateway(
    "eyJhbGci...",
    "gateway-123",
    None,
    None
).await?;

// Save machine token securely (encrypted filesystem storage)
let machine_token = MachineToken::new(
    response.machine_token,
    response.expires_at,
    response.gateway.id,
    response.abilities,
);
save_machine_token("harmony", &machine_token).await?;

Example (Sanctum Authentication)

use runbeam_sdk::{
    RunbeamClient,
    save_machine_token,
    MachineToken,
};

// Create API client with base URL
let client = RunbeamClient::new("https://api.runbeam.io");

// Authorize a gateway with Sanctum token (no validation needed)
let response = client.authorize_gateway(
    "1|abc123def456...",  // Sanctum API token
    "gateway-123",
    None,
    None
).await?;

// Save machine token securely (encrypted filesystem storage)
let machine_token = MachineToken::new(
    response.machine_token,
    response.expires_at,
    response.gateway.id,
    response.abilities,
);
save_machine_token("harmony", &machine_token).await?;

Re-exports

pub use validation::validate_config_toml;

pub use validation::validate_pipeline_toml;

pub use validation::validate_toml;

pub use validation::ValidationError;

pub use runbeam_api::client::RunbeamClient;

pub use runbeam_api::jwt::extract_bearer_token;

pub use runbeam_api::jwt::validate_jwt_token;

pub use runbeam_api::jwt::JwtClaims;

pub use runbeam_api::jwt::JwtValidationOptions;

pub use runbeam_api::resources::AcknowledgeChangesRequest;

pub use runbeam_api::resources::AcknowledgeChangesResponse;

pub use runbeam_api::resources::Authentication;

pub use runbeam_api::resources::Backend;

pub use runbeam_api::resources::BaseUrlResponse;

pub use runbeam_api::resources::Change;

pub use runbeam_api::resources::ChangeAppliedResponse;

pub use runbeam_api::resources::ChangeFailedRequest;

pub use runbeam_api::resources::ChangeFailedResponse;

pub use runbeam_api::resources::ChangeStatusResponse;

pub use runbeam_api::resources::Endpoint;

pub use runbeam_api::resources::Gateway;

pub use runbeam_api::resources::GatewayConfiguration;

pub use runbeam_api::resources::MeshTokenRequest;

pub use runbeam_api::resources::MeshTokenResponse;

pub use runbeam_api::resources::Middleware;

pub use runbeam_api::resources::Network;

pub use runbeam_api::resources::PaginatedResponse;

pub use runbeam_api::resources::PaginationLinks;

pub use runbeam_api::resources::PaginationMeta;

pub use runbeam_api::resources::Pipeline;

pub use runbeam_api::resources::Policy;

pub use runbeam_api::resources::PolicyRules;

pub use runbeam_api::resources::ResourceResponse;

pub use runbeam_api::resources::Service;

pub use runbeam_api::resources::Transform;

pub use runbeam_api::token_storage::clear_machine_token;

pub use runbeam_api::token_storage::clear_token;

pub use runbeam_api::token_storage::load_machine_token;

pub use runbeam_api::token_storage::load_token;

pub use runbeam_api::token_storage::save_machine_token;

pub use runbeam_api::token_storage::save_token;

pub use runbeam_api::token_storage::save_token_with_key;

pub use runbeam_api::token_storage::MachineToken;

pub use runbeam_api::types::ApiError;

pub use runbeam_api::types::AuthorizeResponse;

pub use runbeam_api::types::GatewayInfo;

pub use runbeam_api::types::LookupBy;

pub use runbeam_api::types::ProviderConfig;

pub use runbeam_api::types::ResolveResourceResponse;

pub use runbeam_api::types::ResolutionMeta;

pub use runbeam_api::types::ResolvedResource;

pub use runbeam_api::types::ResourceReference;

pub use runbeam_api::types::ResourceType;

pub use runbeam_api::types::RunbeamError;

pub use runbeam_api::types::StoreConfigRequest;

pub use runbeam_api::types::StoreConfigResponse;

pub use runbeam_api::types::TeamInfo;

pub use runbeam_api::types::UserInfo;

pub use runbeam_api::types::UserToken;

Modules

runbeam_api

storage

validation

TOML configuration validation for Harmony Proxy.