Authlink.Portal.Client.Http 2.2.0

📦 Package Overview

Authlink.Portal.Client.Http provides a ready-to-use, production-grade implementation of the IPortalClient abstraction defined in Authlink.Portal.Client.Core.

🚀 Install

dotnet add package Authlink.Portal.Client.Http

Or via Package Manager:

PM> Install-Package Authlink.Portal.Client.Http

🆕 What's New

v2.2.0

New Features:

• ✅ Status filtering: Filter users by lifecycle status (Active, Inactive, Deleted) in GetUsersAsync
• ✅ Tenant filtering: Filter users by TenantId for multi-tenant scenarios
• ✅ Enhanced queries: Updated HTTP client to properly serialize Status and TenantId query parameters

Example - Filter by Status:

var result = await _client.GetUsersAsync(new GetUsersRequest
{
    Status = UserStatus.Active,
    PageNumber = 1,
    PageSize = 20
});

Example - Filter by Tenant:

var result = await _client.GetUsersAsync(new GetUsersRequest
{
    TenantId = tenantId,
    SearchText = "john",
    PageNumber = 1,
    PageSize = 20
});

v2.1.0

New Features:

• ✅ New lookup methods: GetUserByEmailAsync and GetUserByGovernmentIdAsync for flexible user retrieval
• ✅ Optional authentication: Set AccessToken directly in options or provide custom IAccessTokenProvider
• ✅ Runtime token updates: New MutableAccessTokenProvider allows updating tokens without restarting
• ✅ Automatic auth detection: Extensions method intelligently handles authentication based on configuration

Example - Simple token setup:

builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
    options.AccessToken = "your-token"; // New in v2.1
});

Example - Runtime token refresh:

if (_tokenProvider is MutableAccessTokenProvider mutableProvider)
{
    mutableProvider.SetAccessToken(newToken); // Update token on the fly
}

v2.0

Breaking Changes:

All methods now return ErrorOr<TResponse> instead of throwing exceptions. This provides:

• ✅ Type-safe error handling
• ✅ Comprehensive error information (status codes, response bodies, exception details)
• ✅ Better control flow without try-catch blocks
• ✅ Rich metadata for debugging and logging

🛠️ Usage Examples

Setup

The client supports three authentication approaches. Choose the one that fits your needs:

Option 1: Simple - Static Token (Recommended for Most Cases)

Set the token directly in options. Perfect for service-to-service communication with a static API key:

builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
    options.AccessToken = builder.Configuration["Authlink:Portal:AccessToken"];
});

appsettings.json:

{
  "Authlink": {
    "Portal": {
      "BaseUrl": "https://portal.authlink.co.za",
      "AccessToken": "your-access-token-here"
    }
  }
}

Updating the token at runtime:

When using the static token approach, you can update the token at runtime by injecting MutableAccessTokenProvider:

public class TokenRefreshService
{
    private readonly IAccessTokenProvider _tokenProvider;

    public TokenRefreshService(IAccessTokenProvider tokenProvider)
    {
        _tokenProvider = tokenProvider;
    }

    public async Task RefreshTokenAsync()
    {
        // Get new token from your auth service
        var newToken = await GetNewTokenFromAuthService();

        // Update the token - cast to MutableAccessTokenProvider
        if (_tokenProvider is MutableAccessTokenProvider mutableProvider)
        {
            mutableProvider.SetAccessToken(newToken);
        }
    }
}

Or configure a background service to refresh tokens automatically:

public class TokenRefreshBackgroundService : BackgroundService
{
    private readonly IAccessTokenProvider _tokenProvider;
    private readonly ILogger<TokenRefreshBackgroundService> _logger;

    public TokenRefreshBackgroundService(
        IAccessTokenProvider tokenProvider,
        ILogger<TokenRefreshBackgroundService> logger)
    {
        _tokenProvider = tokenProvider;
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                // Refresh token every 50 minutes (assuming 60 min expiry)
                await Task.Delay(TimeSpan.FromMinutes(50), stoppingToken);

                var newToken = await RefreshTokenAsync();

                if (_tokenProvider is MutableAccessTokenProvider mutableProvider)
                {
                    mutableProvider.SetAccessToken(newToken);
                    _logger.LogInformation("Portal access token refreshed successfully");
                }
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "Failed to refresh portal access token");
            }
        }
    }

    private async Task<string> RefreshTokenAsync()
    {
        // Your token refresh logic here
        throw new NotImplementedException();
    }
}

// Register the background service
builder.Services.AddHostedService<TokenRefreshBackgroundService>();

Option 2: Advanced - Custom Token Provider

Implement IAccessTokenProvider for dynamic tokens (e.g., from user context, token refresh, etc.):

// 1. Implement your token provider
public class HttpContextTokenProvider : IAccessTokenProvider
{
    private readonly IHttpContextAccessor _httpContextAccessor;

    public HttpContextTokenProvider(IHttpContextAccessor httpContextAccessor)
    {
        _httpContextAccessor = httpContextAccessor;
    }

    public Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default)
    {
        var token = _httpContextAccessor.HttpContext?.Request.Headers["Authorization"]
            .FirstOrDefault()?.Replace("Bearer ", "");
        return Task.FromResult(token ?? string.Empty);
    }
}

// 2. Register your provider BEFORE calling AddPortalHttpClient
builder.Services.AddScoped<IAccessTokenProvider, HttpContextTokenProvider>();

// 3. Register the client (it will use your custom provider)
builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
});

Other custom provider examples:

// Token from a service/cache with live updates
public class TokenServiceProvider : IAccessTokenProvider
{
    private readonly ITokenService _tokenService;

    public TokenServiceProvider(ITokenService tokenService)
    {
        _tokenService = tokenService;
    }

    public async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default)
    {
        // Fetch the latest token on every request
        return await _tokenService.GetCurrentTokenAsync(cancellationToken);
    }
}

💡 Tip: If you need token refresh with a custom provider, use Option 1 (static token) with MutableAccessTokenProvider and update it via a background service. This gives you the best of both worlds: simple setup with runtime updates.

Option 3: No Authentication

For public endpoints or when you're handling authentication manually:

builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
    // No AccessToken set, no custom provider registered
});

Basic Usage with Error Handling

public class MyService
{
    private readonly IPortalClient _client;

    public MyService(IPortalClient client)
    {
        _client = client;
    }

    public async Task GetUsersAsync()
    {
        var request = new GetUsersRequest
        {
            PageNumber = 1,
            PageSize = 10
        };

        var result = await _client.GetUsersAsync(request);

        if (result.IsError)
        {
            // Handle error
            var error = result.FirstError;
            Console.WriteLine($"Error: {error.Code} - {error.Description}");

            // Access metadata
            if (error.Metadata.TryGetValue("StatusCode", out var statusCode))
            {
                Console.WriteLine($"HTTP Status: {statusCode}");
            }

            if (error.Metadata.TryGetValue("ResponseBody", out var body))
            {
                Console.WriteLine($"Response: {body}");
            }

            return;
        }

        // Success - use the value
        var response = result.Value;
        Console.WriteLine($"Found {response.TotalCount} users");
        foreach (var user in response.Users)
        {
            Console.WriteLine($"- {user.FirstName} {user.LastName}");
        }
    }
}

Get User by Email

public async Task<ErrorOr<UserDto>> GetUserByEmailAsync(string email)
{
    var result = await _client.GetUserByEmailAsync(new GetUserByEmailRequest
    {
        Email = email
    });

    if (result.IsError)
    {
        return result.Errors;
    }

    return result.Value.User;
}

Get User by Government Identifier

public async Task<ErrorOr<UserDto>> GetUserByGovernmentIdAsync(
    IdentifierKind identifierKind,
    string countryIso2,
    string identifier)
{
    var result = await _client.GetUserByGovernmentIdAsync(new GetUserByGovernmentIdRequest
    {
        IdentifierKind = identifierKind,
        CountryIso2 = countryIso2,
        Identifier = identifier
    });

    if (result.IsError)
    {
        return result.Errors;
    }

    return result.Value.User;
}

Pattern Matching

var result = await _client.GetUserByIdAsync(new GetUserByIdRequest { UserId = userId });

return result.Match(
    user => Ok(user),
    errors => errors[0].Type switch
    {
        ErrorType.NotFound => NotFound(),
        ErrorType.Unauthorized => Unauthorized(),
        ErrorType.Forbidden => Forbid(),
        _ => Problem(errors[0].Description)
    }
);

Switching on Error Type

var result = await _client.CreateUserAsync(request);

if (result.IsError)
{
    var error = result.FirstError;

    return error.Type switch
    {
        ErrorType.Validation => BadRequest(error.Description),
        ErrorType.Conflict => Conflict(error.Description),
        ErrorType.Unauthorized => Unauthorized(),
        ErrorType.Forbidden => Forbid(),
        _ => StatusCode(500, error.Description)
    };
}

return Ok(result.Value);

🔧 Error Types

The client returns specific error types for common scenarios:

📊 Error Metadata

All errors include metadata for detailed diagnostics:

if (result.IsError)
{
    var error = result.FirstError;

    // Available metadata keys:
    // - StatusCode: HTTP status code (int)
    // - StatusCodeName: Status code name (string)
    // - ResponseBody: Raw response content (string)
    // - RequestPath: The path that failed (string)
    // - ExceptionType: Exception type name (string)
    // - ExceptionMessage: Exception message (string)
    // - TypeName: Type that failed to deserialize (string)
}

🔄 Migration from v1.x

Before (v1.x)

// Registration
builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
});

// Usage
try
{
    var response = await _client.UsersAsync(request);
    return Ok(response);
}
catch (HttpRequestException ex)
{
    return StatusCode(500, "Request failed");
}

After (v2.0)

// Registration - Simple approach with static token
builder.Services.AddPortalHttpClient(options =>
{
    options.BaseUrl = "https://portal.authlink.co.za";
    options.AccessToken = "your-token"; // New in v2.0
});

// Usage - ErrorOr-based error handling
var result = await _client.GetUsersAsync(request);

if (result.IsError)
{
    var error = result.FirstError;
    return Problem(error.Description);
}

return Ok(result.Value);

Breaking Changes Summary

1. Authentication: Now supports optional authentication via AccessToken property or custom IAccessTokenProvider
2. Method Naming: Methods follow Get* pattern (e.g., GetUsersAsync, GetUserByIdAsync)
3. Return Type: All methods return ErrorOr<TResponse> instead of TResponse
4. No Exceptions: HTTP errors are returned as Error objects instead of throwing exceptions
5. New Methods: Added GetUserByEmailAsync and GetUserByGovernmentIdAsync

📚 Documentation

https://docs.authlink.co.za

📄 License

MIT