flowfull-rust

Official Rust client and backend starter path for Flowfull backends.

Use this page when you want a Rust API that validates Flowless sessions, protects Axum routes, and can issue Trust tokens for secure backend-to-backend or frontend handoff flows.

What to use

Need	Use
Add the Rust client to an existing Rust backend	cargo add flowfull
Start a complete secure Axum backend	pubflow create rust-backend my-api
Read or clone the backend starter	github.com/pubflow/flowfull-rust-starter

Install the client

cargo add flowfull

Or add it manually:

[dependencies]
flowfull = "0.1.0"

The client is useful for direct Flowfull/Flowless API calls, shared request helpers, and projects that already have their own Axum, Actix, Rocket, or worker-style backend structure.

Start with the Rust backend starter

pubflow create rust-backend my-api
cd my-api
cp .env.example .env
cargo run

The Rust starter is the fastest path when you want a production-shaped backend. It includes:

• Axum + Tokio application setup
• SQLx database pool and health checks
• Flowless Bridge validation through a local validator
• Session extraction from X-Session-Id, session_id cookie, and optional query support
• require_auth, optional_auth, require_roles, require_roles_csv, and require_admin
• Admin-only guard where require_admin accepts only admin
• PASETO v4 Trust token helpers
• Local TTL cache with optional Redis wiring
• CORS, tracing, config validation, Docker, tests, and example routes

Bridge validation model

The starter validates sessions against Flowless Bridge before protected handlers run.

The validation endpoint defaults to /auth/bridge/validate and can be configured for older deployments that still use /api/bridge/validate.

Middleware examples

Protect a route:

use axum::{middleware, routing::get, Router};

let app = Router::new()
    .route("/api/protected", get(protected_handler))
    .route_layer(middleware::from_fn_with_state(state.clone(), require_auth));

Allow anonymous and authenticated users:

let app = Router::new()
    .route("/api/optional", get(optional_handler))
    .route_layer(middleware::from_fn_with_state(state.clone(), optional_auth));

Require one or more roles:

let roles = require_roles(["editor", "admin"]);

let app = Router::new()
    .route("/api/reports", get(reports_handler))
    .route_layer(middleware::from_fn_with_state(state.clone(), roles));

Require CSV-configured roles in code:

let roles = require_roles_csv("support,admin");

Require admin only:

let app = Router::new()
    .route("/api/admin/dashboard", get(admin_dashboard))
    .route_layer(middleware::from_fn_with_state(state.clone(), require_admin()));

require_admin intentionally accepts only admin. If your application wants superadmin, opt in explicitly with require_roles(["admin", "superadmin"]).

Trust tokens

The starter includes PASETO v4 helpers for Trust tokens. Use them when your backend needs to mint a short-lived signed claim after Flowless has validated a session.

Typical uses:

• Internal service calls that should not forward raw session IDs
• Temporary handoff tokens for uploads, exports, or privileged operations
• Auditable claims with explicit expiry

Keep Trust token lifetimes short and rotate keys using your production secret management.

Example routes in the starter

Route	Purpose
GET /	Service metadata
GET /health	Basic liveness
GET /health/db	SQLx database health
GET /health/cache	Cache health
GET /health/all	Full health report
GET /api/public	Public route
GET /api/protected	Requires a valid Flowless session
GET /api/optional	Works with or without a session
GET /api/profile	Session-aware profile example
GET /api/admin/dashboard	Admin-only example
/api/tasks	Mock CRUD routes users can replace

Useful links

• Rust client docs: clients.flowfull.dev/packages/rust
• Rust backend starter: github.com/pubflow/flowfull-rust-starter
• Rust client source: github.com/pubflow/pbfl/tree/main/packages/flowfull-clients/flowfull-rust
• Starter kits: Flowfull Starter Kits
• Clients docs home: Flowfull Clients
• Request center: pubflow.com/requests