Origin Auth .NET SDK

Official .NET SDK for the Origin Auth Platform. Provides typed clients for every REST resource, automatic exponential-backoff retry with token refresh, and first-class dependency-injection support.

Package: Origin.Client Version: 1.0.0 Targets: net10.0 License: MIT

Features

Typed clients (10 resources)

• AuthClient — login, logout, token refresh, registration, password reset, user profile
• UsersClient — CRUD, list, search
• TenantsClient — CRUD, settings, branding, MFA policy
• OAuthClient — authorize, token, introspect, revoke, OIDC discovery
• MfaClient — TOTP/WebAuthn enroll/verify, recovery codes, device list
• SessionsClient — list, revoke, "log out everywhere"
• WebhooksClient — subscription CRUD, delivery list, replay
• BillingClient — plans, subscriptions, invoices
• AuditClient — search, export, status, download
• HealthClient — ping, status (per-component health)
• Plus a low-level AuthenticationApiClient (Logto-compatible) wrapped by AuthClient.

Built-in resilience

• Polly-based RetryHandler with exponential back-off and jitter (defaults: 5 retries, 1s → 2s → 4s → 8s → 16s, max 32s).
• Retryable status codes: 429 Too Many Requests, 503 Service Unavailable, 504 Gateway Timeout.
• 401 Unauthorized: single refresh-and-retry via OriginClientOptions.OnUnauthorizedAsync.
• Network errors (timeouts, connection resets) trigger automatic retry.
• Fully configurable via RetryPolicyOptions (e.g. ForTesting for deterministic 100ms test delays).

Dependency-injection ready

builder.Services.AddOriginClient(options =>
{
    options.BaseUrl = builder.Configuration["Origin:BaseUrl"]!;
    options.ClientId = builder.Configuration["Origin:ClientId"]!;
    options.ClientSecret = builder.Configuration["Origin:ClientSecret"];
});

The OriginClient facade (and all 10 typed sub-clients) can be injected into controllers, services, or background workers.

Installation

# Add to your .NET project
dotnet add package Origin.Client

Configuration

Explicit options

var options = new OriginClientOptions
{
    BaseUrl = "https://api.uat.origin-auth.com",   // EXAMPLE — override per environment
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",           // omit for public clients
    TimeoutSeconds = 30,                           // per-request HTTP timeout
};

Environment variables (BR-23-NEW-008)

Every option has an environment-variable fallback. Explicit property assignments take precedence:

// Zero-config: resolve everything from environment variables
builder.Services.AddOriginClient(_ => { });

When BaseUrl resolves to the production default (https://api.origin-auth.phanes.com) with no explicit override, the SDK emits a one-shot trace warning at first request. Always set BaseUrl (or ORIGIN_AUTH_BASE_URL) to your environment's API host. Other defaults: Authority derives from {BaseUrl}/realms/origin; DefaultScope = openid profile email offline_access; ValidateSslCertificates = true.

Quick start

using Origin.Client;

// Via DI
public class MyService(OriginClient origin) { ... }

// Or directly
var options = new OriginClientOptions
{
    BaseUrl = "https://api.origin-auth.phanes.com",
    ClientId = "your-client-id",
    ClientSecret = "your-client-secret",
};

var httpClient = new HttpClient();
var origin = new OriginClient(httpClient, options);

// Login
var tokens = await origin.Auth.LoginAsync(new LoginRequest
{
    ClientId = options.ClientId,
    Username = "alice@example.com",
    Password = "p@ssw0rd!",
});

// List users
var users = await origin.Users.ListAsync(tenantId: "tenant_123", page: 1, pageSize: 50);
foreach (var u in users.Items) Console.WriteLine(u.Email);

// Health check
var healthy = await origin.Health.PingAsync();

Authentication flows

Authorization Code (browser redirect)

// Server-side: exchange the code from the callback URL
var tokenResponse = await origin.OAuth.ExchangeCodeAsync(new ExchangeCodeRequest
{
    Code = "auth-code-from-callback",
    RedirectUri = "https://your-app.com/callback",
});

Client Credentials (machine-to-machine)

var token = await origin.OAuth.ClientCredentialsAsync(scope: "api:read");

Token introspection & revocation (RFC 7662 / RFC 7009)

var info = await origin.OAuth.IntrospectAsync(accessToken);
if (info.Active) { /* still valid */ }

await origin.OAuth.RevokeAsync(refreshToken, "refresh_token");

Retry semantics

The SDK automatically retries failed requests via the RetryHandler. Defaults:

Configure your own policy:

var handler = new RetryHandler(new HttpClientHandler(), new RetryPolicyOptions
{
    MaxRetries = 10,
    BaseDelaySeconds = 0.5,
    MaxDelaySeconds = 60,
    JitterFactor = 0.5,
});

Error handling

All client methods throw HttpRequestException on non-success status codes (after retries are exhausted). To inspect the error body:

try
{
    var user = await origin.Users.GetByIdAsync("invalid-id");
}
catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.NotFound)
{
    // Handle 404
}

For OAuth flows, the low-level AuthenticationApiClient throws typed ApiException subclasses (RateLimitApiException, ErrorApiException, QuotaLimit).

Target framework

The package targets .NET 10 (net10.0). Origin.Client owns its public contracts and does not require a source-tree reference to Origin.Common.

License

MIT — see the LICENSE file for the full text.

Support

Issues: code.phanes.ltd/oelite/uranus/origin-auth/-/issues

• API docs: code.phanes.ltd/oelite/uranus/origin-auth/-/wikis