Axum

Better Auth provides first-class integration with Axum via the axum feature flag, including automatic route mounting, session extractors, and type-safe access to the current user.

Setup

Cargo.toml

[dependencies]
better-auth = { version = "0.6", features = ["axum"] }
axum = "0.8"
tokio = { version = "1", features = ["full"] }

Mounting Auth Routes

Use .axum_router() to convert the auth instance into an Axum Router:

use better_auth::{AuthConfig, BetterAuth};
use better_auth::plugins::{
    EmailPasswordPlugin, SessionManagementPlugin,
    PasswordManagementPlugin, AccountManagementPlugin,
};
use better_auth::adapters::MemoryDatabaseAdapter;
use better_auth::handlers::AxumIntegration;
use axum::Router;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AuthConfig::new("your-very-secure-secret-key-at-least-32-chars-long")
        .base_url("http://localhost:8080");

    let auth = Arc::new(
        BetterAuth::new(config)
            .database(MemoryDatabaseAdapter::new())
            .plugin(EmailPasswordPlugin::new().enable_signup(true))
            .plugin(SessionManagementPlugin::new())
            .plugin(PasswordManagementPlugin::new())
            .plugin(AccountManagementPlugin::new())
            .build()
            .await?
    );

    let auth_router = auth.clone().axum_router();

    let app = Router::new()
        .nest("/auth", auth_router)
        .with_state(auth);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;

    Ok(())
}

What Gets Mounted

.axum_router() automatically registers:

All plugin routes (sign-up, sign-in, sessions, etc.)
GET /ok — health check
GET /health — service health
GET /reference/openapi.json — OpenAPI specification
POST /update-user — user profile updates
POST /delete-user — account deletion
POST /change-email — email changes

With the router nested under /auth, endpoints become /auth/sign-up/email, /auth/get-session, etc.

Session Extractors

Better Auth provides Axum extractors that automatically validate the session token and give you the current user — no manual middleware needed.

`CurrentSession` — Require Authentication

Use CurrentSession<DB> in your handler signature to require a valid session. Returns 401 Unauthorized automatically if no valid session is found.

use better_auth::handlers::CurrentSession;
use better_auth::adapters::MemoryDatabaseAdapter;
use better_auth::AuthUser; // trait for .id(), .email(), etc.
use axum::{Json, response::IntoResponse};

async fn get_profile(
    session: CurrentSession<MemoryDatabaseAdapter>,
) -> impl IntoResponse {
    Json(serde_json::json!({
        "id": session.user.id(),
        "email": session.user.email(),
        "name": session.user.name(),
    }))
}

CurrentSession provides two public fields:

Field	Type	Description
`user`	`DB::User`	The authenticated user (implements `AuthUser`)
`session`	`DB::Session`	The current session (implements `AuthSession`)

`OptionalSession` — Optional Authentication

Use OptionalSession<DB> for routes that should work for both authenticated and anonymous users. Never returns an error — wraps the result in Option.

use better_auth::handlers::OptionalSession;
use better_auth::adapters::MemoryDatabaseAdapter;
use better_auth::AuthUser;
use axum::{Json, response::IntoResponse};

async fn home(
    session: OptionalSession<MemoryDatabaseAdapter>,
) -> impl IntoResponse {
    let user_info = session.0.map(|s| {
        serde_json::json!({
            "id": s.user.id(),
            "email": s.user.email(),
        })
    });

    Json(serde_json::json!({
        "message": "Welcome",
        "user": user_info,
    }))
}

Token Extraction

Both extractors look for the session token in this order:

Authorization: Bearer <token> header
Session cookie (name from SessionConfig::cookie_name, default better-auth.session-token)

Full Example

use axum::{Json, Router, response::IntoResponse, routing::get};
use better_auth::adapters::MemoryDatabaseAdapter;
use better_auth::handlers::{AxumIntegration, CurrentSession, OptionalSession};
use better_auth::plugins::{EmailPasswordPlugin, SessionManagementPlugin};
use better_auth::{AuthBuilder, AuthConfig, AuthUser};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = AuthConfig::new("your-very-secure-secret-key-at-least-32-chars-long")
        .base_url("http://localhost:8080");

    let auth = Arc::new(
        AuthBuilder::new(config)
            .database(MemoryDatabaseAdapter::new())
            .plugin(EmailPasswordPlugin::new().enable_signup(true))
            .plugin(SessionManagementPlugin::new())
            .build()
            .await?
    );

    let auth_router = auth.clone().axum_router();

    let app = Router::new()
        .route("/api/profile", get(get_profile))
        .route("/api/public", get(public_route))
        .nest("/auth", auth_router)
        .with_state(auth);

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
    axum::serve(listener, app).await?;

    Ok(())
}

/// Protected route — requires authentication
async fn get_profile(
    session: CurrentSession<MemoryDatabaseAdapter>,
) -> impl IntoResponse {
    Json(serde_json::json!({
        "id": session.user.id(),
        "email": session.user.email(),
        "name": session.user.name(),
    }))
}

/// Public route — works for both authenticated and anonymous users
async fn public_route(
    session: OptionalSession<MemoryDatabaseAdapter>,
) -> impl IntoResponse {
    let user = session.0.map(|s| s.user.id().to_string());
    Json(serde_json::json!({
        "authenticated": user.is_some(),
        "user_id": user,
    }))
}

Request/Response Conversion

The integration automatically converts between Axum and Better Auth types:

Headers: All request headers are forwarded
Body: Request body is read as bytes and passed through
Query: Query parameters are parsed from the URL
Status codes: Mapped directly to HTTP status codes
Response headers: Set-Cookie and other headers are forwarded

Axum

On this page