Ledger Bridge

The Ledger bridge connects Authsome to the Ledger billing and metering extension. When configured, Authsome records usage events (monthly active users, API key validations, MFA enrollments) to Ledger's metering system and checks feature entitlements before allowing certain operations.

Interface

The bridge.Ledger interface is defined in github.com/xraph/authsome/bridge:

type Ledger interface {
    RecordUsage(ctx context.Context, featureKey string, quantity int64) error
    CheckEntitlement(ctx context.Context, featureKey string) (allowed bool, err error)
}

Setup with the Ledger adapter

import (
    "github.com/xraph/authsome"
    "github.com/xraph/authsome/bridge/ledgeradapter"
    "github.com/xraph/ledger"
)

// Build the Ledger engine (see Ledger docs for full setup).
ledgerEng, err := ledger.New(
    ledger.WithStore(ledgerStore),
)
if err != nil {
    log.Fatal(err)
}

// Wrap in the Authsome adapter.
ledgerBridge := ledgeradapter.New(ledgerEng)

// Register with Authsome.
eng, err := authsome.New(
    authsome.WithStore(pgStore),
    authsome.WithLedger(ledgerBridge),
)

Usage events recorded by Authsome

When a Ledger bridge is configured, Authsome records the following usage events:

Entitlement checks

Before allowing certain operations, Authsome checks entitlements with Ledger. If the entitlement check returns allowed: false, the operation is rejected with an appropriate error:

This allows you to implement plan-based feature gating at the Ledger level without modifying Authsome's plugin configuration. A "Starter" plan can disable SSO and custom domains while a "Business" plan enables them.

Standalone development stub

During development, use the built-in NoopLedger stub. The noop ledger returns allowed: true for all entitlement checks (fail-open), meaning all features are available in development:

import "github.com/xraph/authsome/bridge"

eng, err := authsome.New(
    authsome.WithStore(memory.New()),
    authsome.WithLedger(bridge.NewNoopLedger()),
)