WexHealth 1.0.0-beta.1

WexHealth

WexHealth is the official .NET SDK for the Wex Health and Benefits APIs.

All external APIs merged for documentation and discovery

• API version: 1.0.22
• SDK version: 1.0.0-beta.1

Features

• Typed clients for every endpoint defined in the OpenAPI specification.
• OAuth2 Client Credentials authentication with automatic token acquisition, refresh, and thread-safe caching. Compatible with static bearer tokens for migration scenarios.
• Resilience built in: timeout + retry pipeline (Polly v8) with exponential backoff, jitter, and Retry-After support.
• First-class ASP.NET Core integration through AddWexHealthSdk(...) and IHttpClientFactory.
• Multi-targeting: net6.0, net7.0, and net8.0 assemblies in a single package; NuGet selects the right one for your project.
• Strong-named, signed, and timestamped package on NuGet.org.

Installation

.NET CLI

dotnet add package WexHealth

Package Manager Console

Install-Package WexHealth

PackageReference

<PackageReference Include="WexHealth" Version="1.0.0-beta.1" />

Dependencies

The package brings the following runtime dependencies:

• Newtonsoft.Json >= 13.0.4
• JsonSubTypes >= 1.8.0
• Polly >= 8.6.5
• Polly.Core >= 8.6.5
• Microsoft.Extensions.Http >= 8.0.0
• Microsoft.Extensions.Logging.Abstractions >= 8.0.0

Quick Start

using System;
using WexHealth.Api;
using WexHealth.Models;
using WexHealth.Client;

// 1. Provide OAuth2 credentials via environment variables (see "Authentication" below):
//    WEX_OAUTH2_TOKEN_URL, WEX_OAUTH2_CLIENT_ID, WEX_OAUTH2_CLIENT_SECRET

var config = new Configuration
{
    BasePath = "https://api.example.com" // production base URL provided by Wex
};

var claims = new ClaimsApi(config);

var personId    = Guid.Parse("550e8400-e29b-41d4-a716-446655440000");
var claimNumber = "11BPEB1210513P0000101";

Models.ClaimDTO claim = claims.GetClaim(personId, claimNumber);
Console.WriteLine(claim);

async overloads (GetClaimAsync, GetClaimsForParticipantAsync, …) are available for every operation.

Authentication

The SDK supports two authentication modes against the Bearer-protected API:

1. OAuth2 Client Credentials (recommended) — the SDK acquires, caches, and refreshes access tokens automatically.
2. Static Bearer Token — supply a long-lived token yourself for migration or testing.

OAuth2 Client Credentials (recommended)

Option 1 — Environment variables (zero-code)

The SDK detects OAuth2 credentials from environment variables and configures itself on first use:

# Linux / macOS
export WEX_OAUTH2_TOKEN_URL="https://auth.example.com/oauth/token"
export WEX_OAUTH2_CLIENT_ID="your-client-id"
export WEX_OAUTH2_CLIENT_SECRET="your-client-secret"
export WEX_OAUTH2_AUDIENCE="https://api.example.com"   # optional

# Windows PowerShell
$env:WEX_OAUTH2_TOKEN_URL    = "https://auth.example.com/oauth/token"
$env:WEX_OAUTH2_CLIENT_ID    = "your-client-id"
$env:WEX_OAUTH2_CLIENT_SECRET = "your-client-secret"
$env:WEX_OAUTH2_AUDIENCE     = "https://api.example.com"   # optional

var config = new Configuration { BasePath = "https://api.example.com" };

// Authentication is auto-configured from environment variables.
var claims = new ClaimsApi(config);

Option 2 — Programmatic configuration

using WexHealth.Api;
using WexHealth.Auth;
using WexHealth.Client;

var oauth = new OAuth2ClientCredentialsAuth(
    tokenUrl:     "https://auth.example.com/oauth/token",
    clientId:     "your-client-id",
    clientSecret: "your-client-secret",
    audience:     "https://api.example.com"); // optional

var config = new Configuration { BasePath = "https://api.example.com" };
var claims = new ClaimsApi(config);
claims.ApiClient.SetAuthentication("bearerAuth", oauth);

Token-management defaults:

• Refresh buffer: tokens are renewed 60 seconds before expiry.
• Token retry: up to 3 attempts with exponential backoff on token-endpoint failures.
• Concurrency: thread-safe; concurrent API calls share a single in-memory token.
• Transport: the token endpoint must use HTTPS (constructor throws otherwise).

Static Bearer Token

var config = new Configuration
{
    BasePath    = "https://api.example.com",
    AccessToken = "YOUR_BEARER_TOKEN"
};

var claims = new ClaimsApi(config);

Static tokens do not refresh. Renew the token in your application code before it expires.

ASP.NET Core Integration

For ASP.NET Core, use AddWexHealthSdk(...) to register typed clients with IHttpClientFactory. The SDK provides the API surface; your application owns the base URL, authentication handler, and resilience overrides.

using WexHealth.Api;
using WexHealth.DependencyInjection;

builder.Services.AddTransient<MyTokenHandler>();

builder.Services.AddWexHealthSdk(sdk =>
{
    sdk.AddApi<IClaimsApi, ClaimsApi>(
        configureClient: client =>
        {
            // Required: BaseAddress must be set or AddApi will throw.
            client.BaseAddress = new Uri(builder.Configuration["WexHealth:BaseUrl"]!);
        },
        configureHttpClientBuilder: http =>
        {
            // Optional: attach auth, telemetry, or extra delegating handlers.
            http.AddHttpMessageHandler<MyTokenHandler>();
        });
});

Notes:

• HttpClient.BaseAddress is required — InvalidOperationException if not set.
• Authentication is the application's responsibility through delegating handlers (or Configuration.AccessToken for a static bearer token).
• Resilience (timeouts, retries) can be overridden per registration through the IHttpClientBuilder callback.
• Multiple AddApi<>() calls inside a single AddWexHealthSdk(...) register multiple typed clients; duplicate registrations of the same interface are no-ops.
• Resolved API instances are safe for concurrent use within a DI scope.

Resilience (Retry & Timeout)

Every HTTP request goes through a Polly v8 resilience pipeline composed as Timeout → Retry → HTTP Request.

Defaults

Retries trigger on:

• 5xx server errors;
• network/IO failures and timeout exceptions;
• HTTP 408 (Request Timeout);
• HTTP 429 (Too Many Requests) — only when a Retry-After header is present.

Retries are not issued for other 4xx client errors.

Customization

using WexHealth.Client;

RetryConfiguration.HttpPipeline = RetryConfiguration.CreatePipeline(
    maxRetries:                   5,
    timeoutSeconds:               60,
    zeroDelay:                    false,
    maxExponentialBackoffSeconds: 2,
    maxRetryAfterSeconds:         30);

For full control, assign your own ResiliencePipeline<HttpResponseMessage>:

using Polly;
using Polly.Retry;
using WexHealth.Client;

RetryConfiguration.HttpPipeline = new ResiliencePipelineBuilder<HttpResponseMessage>()
    .AddTimeout(TimeSpan.FromSeconds(45))
    .AddRetry(new RetryStrategyOptions<HttpResponseMessage>
    {
        MaxRetryAttempts = 3,
        Delay            = TimeSpan.FromSeconds(2),
        ShouldHandle     = new PredicateBuilder<HttpResponseMessage>()
            .Handle<HttpRequestException>()
            .HandleResult(r => (int)r.StatusCode >= 500)
    })
    .Build();

Logging

The SDK integrates with Microsoft.Extensions.Logging. When a logger is wired into the ApiClient, the SDK emits structured log entries for retries, timeouts, and request outcomes; the resilience pipeline manages its own context internally, so consumers do not need to interact with Polly directly.

For direct (non-DI) usage, pass an ILogger<ApiClient> to ApiClient and reuse that instance across the typed API classes:

using Microsoft.Extensions.Logging;
using WexHealth.Api;
using WexHealth.Client;

using var loggerFactory = LoggerFactory.Create(builder => builder.AddConsole());
var logger = loggerFactory.CreateLogger<ApiClient>();

var config    = new Configuration { BasePath = "https://api.example.com" };
var apiClient = new ApiClient(config.BasePath, logger);
var claims    = new ClaimsApi(apiClient, apiClient, config);

For ASP.NET Core, register your logger normally — IHttpClientFactory forwards request/response logging through the configured providers, and DI-resolved typed clients pick up the application's ILogger automatically.

For correlation IDs, log levels, and field redaction, configure Microsoft.Extensions.Logging filters and providers as you would for any other typed-client library — the SDK does not impose its own log format.

Error Handling

The SDK surfaces three categories of exceptions:

using Microsoft.Extensions.Logging;
using WexHealth.Api;
using WexHealth.Auth;
using WexHealth.Client;

// Inputs and dependencies (see the Quick Start and Logging sections):
//   ILogger    logger      — resolved from your DI container or LoggerFactory
//   ClaimsApi  claims      — configured per Quick Start
//   Guid       personId    — domain identifier from your application
//   string     claimNumber — domain identifier from your application

try
{
    var claim = await claims.GetClaimAsync(personId, claimNumber);
}
catch (OAuth2TokenException ex)
{
    // Token endpoint failed — check credentials, audience, and connectivity.
    logger.LogError(ex, "OAuth2 token acquisition failed");
}
catch (ApiException ex) when (ex.ErrorCode == 404)
{
    // Resource not found — surface a domain-specific error to the caller.
}
catch (ApiException ex)
{
    // Other API errors — inspect ex.ErrorCode, ex.ErrorContent, ex.Headers.
    logger.LogError(ex, "Wex Health API call failed: {Status}", ex.ErrorCode);
}

Common OAuth2 errors:

API Reference

The SDK exposes one typed client per tag in the OpenAPI specification. Method names match the operation IDs; XML documentation is shipped with the package, so IntelliSense will surface parameters and return types directly in your IDE.

All API paths are relative to Configuration.BasePath.

Endpoints

For request and response schemas, refer to the official API reference at the Wex Developer Portal or to the type definitions exposed by the WexHealth.Models namespace.

Framework Compatibility

NuGet automatically selects the correct assembly based on your project's <TargetFramework>.

SDK Tracking Headers

The SDK adds a User-Agent header to every request to aid server-side diagnostics and rate-limit accounting. The format is:

WexHealth/Health-SDK/<sdk-version> (C#/<runtime-version>; <os-version>)

This header contains no personal data and cannot be disabled by configuration.

Versioning

WexHealth follows Semantic Versioning 2.0:

• MAJOR — incompatible changes to the public API surface.
• MINOR — new endpoints or optional fields, fully backward compatible.
• PATCH — documentation or non-API changes.

Release notes for each version are available on the package page at https://www.nuget.org/packages/WexHealth.

Support

• API documentation: Wex Developer Portal
• Email:

Report security vulnerabilities by email to the address above. Please do not disclose security issues in public channels until they have been acknowledged and a remediation plan is in place.

License

Released under the MIT License.