KeyInteractive.Common.Api.Users 2.2.0

Key Interactive.Common.Api.Users

KeyInteractive.Common.Api.Users is the official .NET client for the Key Interactive Users API ("Key Interactive Accounts"). It gives your app a ready-to-use IApiConsumer/ApiConsumer service wrapping registration, login, enrollment, profile/password management, and the "Sign in with Key Interactive" flow (Authorize/Consent/Poll) behind simple method calls, instead of writing HTTP clients by hand.

This package supersedes the older KeyInteractive.API.Common package (namespace KeyInteractiveCommon) — if you're migrating from it, see the notes at the bottom of this README.

It's built on KeyInteractive.Common.Api, which provides the generic API-consuming plumbing (response envelope, retry, JWT handling) that ApiConsumer inherits.

Requirements

Targets .NET 8.0 or later (net8.0, net10.0).

Installation

dotnet add package KeyInteractive.Common.Api.Users

Configuration

Configure your credentials once at startup with ApiSettings.Configure:

using KeyInteractive.Common.Api.Users.Configuration;
using KeyInteractive.Common.Api.Users.Enums;

ApiSettings.Configure(builder => builder
    .ConfigureApiKey("your-api-key")
    .ConfigureApplicationId("your-application-id")
    .SetApiVersion(EApiVersion.V1)
    .SetCustomApiBaseUri("https://accounts.keyinteractive.it/")
    .ConfigureDeviceInfo(Environment.MachineName, "127.0.0.1")
    .Build());

Dependency injection (Blazor Server / ASP.NET Core)

// Program.cs
builder.Services.AddScoped<ITokenProvider, TokenProvider>();
builder.Services.AddHttpClient<IApiConsumer, ApiConsumer>();

ITokenProvider must be registered Scoped: it holds the current user's JWT for one Blazor circuit. If your site also talks to another API built on KeyInteractive.Common.Api, give that consumer its own ITokenProvider and a distinct StorageKeyPrefix — see the KeyInteractive.Common.Api README for details. This package's own storage key prefix is fixed to "ki" for backward compatibility with existing sessions.

Usage examples

Register and log in

using KeyInteractive.Common.Api.Users.DTO.UsersApi;

var registration = await apiConsumer.RegisterBasicUser(new BasicUserRegistrationDto
{
    Username = "jdoe",
    Email = "jdoe@example.com",
    Password = "Sup3rSecret!",
    ConfirmPassword = "Sup3rSecret!",
    DateOfBirth = new DateTime(1990, 1, 1),
    AcceptedPrivacy = true,
    AcceptedPrivacyDate = DateTime.UtcNow,
});

var login = await apiConsumer.Login(new UserLoginDTO(
    loginCredentials: "jdoe@example.com",
    password: "Sup3rSecret!",
    deviceName: Environment.MachineName,
    deviceIp: "127.0.0.1"));

if (login.Success)
{
    Console.WriteLine($"Welcome, {login.LoginResponse.ActiveUser.Name}!");
}

Read the current user's profile

var profile = await apiConsumer.GetProfile();

if (profile.Success)
{
    Console.WriteLine(profile.UserProfile.Email);
}

"Sign in with Key Interactive" — server-to-server token exchange

Use a separate ApiConsumer instance configured with your third-party application's own ApiKey/ApplicationKey (not the Key Interactive site's own):

var exchange = await apiConsumer.ExchangeAuthorizationCode(new AuthorizeTokenExchangeDto
{
    Code = codeFromRedirect,
    RedirectUri = "https://your-app.example.com/callback",
});

if (exchange.Success)
{
    // apiConsumer is now authenticated as the linked user (SetAuthTokens was applied automatically)
    var user = exchange.TokenData.ActiveUser;
}

For the "standard"/polling mode (no redirect_uri), poll instead:

var poll = await apiConsumer.PollAuthorizeToken(new AuthorizePollDto { State = yourGeneratedState });

if (poll.Success)
{
    // token acquired, same as ExchangeAuthorizationCode
}
else if (poll.ErrorMessage == "authorization_pending")
{
    // keep polling
}

Report and read purchases

Report a billable event server-to-server (application credentials only, no user token):

await apiConsumer.ReportPurchase(new ReportPurchaseDto
{
    UserId = 42,
    ExternalId = "INV-2026-00042", // distinct per renewal for subscriptions
    Description = "Pro plan — monthly",
    AmountMinor = 1999,
    Currency = "EUR",
    Status = EPurchaseStatus.Paid,
    PurchaseDate = DateTime.UtcNow,
});

ReportPurchase is an idempotent upsert keyed on (your application, ExternalId): resend the same ExternalId with Status = EPurchaseStatus.Refunded to record a refund.

The authenticated user reads their own purchase history (optionally filtered by date range):

var purchases = await apiConsumer.GetMyPurchases(fromUtc: DateTime.UtcNow.AddMonths(-12));

if (purchases.Success)
{
    foreach (var p in purchases.Purchases)
        Console.WriteLine($"{p.ApplicationName}: {p.Description} — {p.AmountMinor / 100m} {p.Currency}");
}

See IApiConsumer for the full list of available operations (registration, enrollment, profile/password management, purchases, and the full Authorize/Consent/Poll flow).

Migrating from KeyInteractive.API.Common

• Namespace changed from KeyInteractiveCommon.* to KeyInteractive.Common.Api.Users.* (DTOs, responses, models, enums) and KeyInteractive.Common.Api.* (the response envelope KiApiResponse/KiApiResponseData, now shared plumbing).
• IApiConsumer/ApiConsumer public surface and behavior are unchanged: same constructor signature, same endpoints, same retry/token-rotation behavior. Existing logged-in users are unaffected — the refresh token storage key prefix (ki_auth_token/ki_auth_refresh_token) is unchanged.
• ApiSettings.Configure(...) usage in Program.cs is unchanged.