Crate stackure 

Stackure is the Rust SDK for the Stackure authentication API.

Stackure provides passwordless B2B authentication. This SDK wraps the public API behind seven free functions and a tower middleware.

Quickstart

Protect an axum app:

let app = app.layer(stackure::auth(APP_ID, &["can_approve_invoice"]));

APP_ID is the app’s UUID as registered in Stackure. The layer works in any tower stack — axum, tonic, or hyper.

Access the authenticated user inside a handler:

let user = stackure::user_from_request(parts);

Manual verification without middleware:

let result = stackure::verify(APP_ID, parts, &[]).await;
if result.authenticated {
    // use result.user
}

Send a magic-link email:

let response = stackure::send_magic_link("user@example.com", Some(APP_ID)).await;

Log the user out, ending their access everywhere. Mount it for every method on the logout path. Trigger it with a form or button that POSTs from the app’s own page; a link or any other request is sent to Stackure’s sign-out page, where the user confirms. Awaiting it yields the redirect response, never an error:

async fn logout(parts: http::request::Parts) -> axum::response::Response {
    stackure::logout(&parts).await
}

let app: Router = Router::new().route("/logout", any(logout));

Sign-in handoff

Stackure’s session cookie is scoped to the Stackure host and is never visible to your app. After a successful magic-link sign-in, Stackure hands the browser back to the app’s registered URL with a session_token POST form field: an app-scoped session token valid only for this app, accepted by the validate endpoint for your app ID and never by Stackure itself.

The auth layer consumes it automatically: it validates the token, stores it in a cookie on your own domain and redirects to the same URL as a GET. Invalid tokens are ignored, and handoff bodies over 4 KB are ignored (treated as no token).

Session binding

Sessions are not bound to the browser’s user agent or IP address. The SDK still forwards the original User-Agent and X-Forwarded-For on every validation call, but they are informational only; validation does not depend on them.

Every request with a session token is validated against Stackure, so revoking a session takes effect immediately. Requests without a well-formed token get the sign-in URL without a Stackure call.

Content negotiation

The auth layer inspects the Accept header. Browser requests (Accept: text/html) redirect to the sign-in URL on 401. API requests (Accept: application/json) receive a JSON error body.

Configuration

STACKURE_APP_SECRET must be set to the app secret shown when the app was registered (or last rotated) in Stackure. It is sent as the X-App-Secret header on every call except the sign-out made by logout, which carries the user’s session token instead; the first call that needs it fails with StackureError::Validation when it is unset. STACKURE_BASE_URL overrides the API host (default https://stackure.com).

A newly registered app is not usable by anyone, even its creator, until it is shared with the organization or assigned to a team in Stackure. Do that before testing sign-in.

Every SDK call has one 2-second wall-clock deadline covering connect, headers, body and the single retry. The SDK retries once, after 500 ms, on a 5xx response or a connection failure, and only if more than 500 ms of the deadline remain. A timeout, including while reading the body, surfaces as StackureError::Timeout and is never retried.

Errors

Every function except verify and logout returns StackureError. logout never returns an error: a failed sign-out call still ends in a redirect. Match on the variant, or call StackureError::code for the same lowercase category string the other Stackure SDKs expose as .code.

Re-exports

pub use errors::StackureError;

pub use middleware::Auth;

pub use middleware::AuthLayer;

pub use middleware::auth;

pub use middleware::logout;

pub use middleware::user_from_request;

pub use middleware::verify;

pub use types::MagicLinkResponse;

pub use types::Session;

pub use types::User;

pub use types::VerifyError;

pub use types::VerifyResult;

Modules

errors

Stackure SDK error type.

middleware

Session verification and the tower authentication middleware.

types

Types returned by the Stackure SDK.

validation

Input validation for the Stackure SDK.

Constants

SESSION_COOKIE

Name of the session cookie the SDK reads and writes.

TOKEN_PARAM

Name of the sign-in handoff parameter Stackure sends back.

Functions

base_url

Resolve STACKURE_BASE_URL from the environment, else production.

send_magic_link

Send a passwordless sign-in email.

validate_session

Validate the request’s session against Stackure.