KindeManagementApiClient 0.0.4-alpha

This is a prerelease version of KindeManagementApiClient.
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package KindeManagementApiClient --version 0.0.4-alpha                
NuGet\Install-Package KindeManagementApiClient -Version 0.0.4-alpha                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="KindeManagementApiClient" Version="0.0.4-alpha" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add KindeManagementApiClient --version 0.0.4-alpha                
#r "nuget: KindeManagementApiClient, 0.0.4-alpha"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install KindeManagementApiClient as a Cake Addin
#addin nuget:?package=KindeManagementApiClient&version=0.0.4-alpha&prerelease

// Install KindeManagementApiClient as a Cake Tool
#tool nuget:?package=KindeManagementApiClient&version=0.0.4-alpha&prerelease                

Kinde management API SDK for .NET

License: MIT

A convenient interface for consuming the Kinde Management API that manages the access token refresh flow and transient network errors for you.

Note This library is still in development, so breaking changes are possible, althought I don't expect much to change in the interface.

This SDK supports the following platforms:

  • .NET 7
  • .NET 8

Installation

You should install KindeManagementApiClient with NuGet

dotnet add package KindeManagementApiClient

Or via Visual Studio Package Manager Console:

Install-Package KindeManagementApiClient

These commands will install the KindeManagementApiClient and all of its dependencies.

Configure options

Before you start using the library you need to:

  • create a Machine to machine (M2M) application and enable the Kinde Management API connection in the app's settings.
  • add this configuration to your appsettings.json file or other json file that is added to your project.
{
  "KindeApiClientOptions": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "Domain": "https://<your-business-name>.kinde.com",
    "Audience": "https://<your-business-name>.kinde.com/api"
  }
}

These settings are going to be validated at the application start. If you forget to add them, or for example the domain isn't a valid URL, you will get the Microsoft.Extensions.Options.OptionsValidationException exception.

Warning You should never expose your ClientSecret in the appsettings.json. In development you can use dotnet secrets like the example below. In production you should use something like Azure Key Vault.

# if you haven't already initialized the user secrets:
dotnet user-secrets init --project <your-project-in-solution>

# make sure you don't make a typo
dotnet user-secrets set "KindeApiClientOptions:ClientSecret" "<your-secret>" --project <your-project-in-solution>

# see all secrets:
dotnet user-secrets list --project <your-project-in-solution>

Important You must turn on the Kinde Management API in the settings of your Machine to machine application! Otherwise, your machine to machine app won't be whitelisted to get the OAuth2 token.

Registering with IServiceCollection

To register KindeManagementApiClient services:

services.AddKindeApiClient();

This registers:

  • IKindeApiClient
  • IMemoryCache
  • IOptions<KindeApiClientOptions>
  • and some other internal services

And adds:

  • IAsyncRetryPolicy to the http client which handles the transient network errors, as well as the 429 HTTP status code (too many requests).

Usage

This library takes care of requesting and refreshing the access tokens for you, so you don't have to do it yourself, just fill in the appsettings.json.

In order to consume the API, you need to inject the IKindeApiClient through the constructor:

using FluentResults;

public sealed class MyAmazingService
{
    private readonly IKindeApiClient _client;
    
    public MyAmazingService(IKindeApiClient client)
        => _client = client;
    
    public async Task<User?> GetUserByIdAsync(string userId)
    {
        var response = await _client.GetUser(userId);
        
        if (!response.IsSuccessStatusCode)
        {
            return null;
        }
        
        return response.Content;
    }
    
    // since the client doesn't throw exceptions by default,
    // you can use something like FluentResults
    public async Task<Result<string>> CreateOrganizationAsync(string organizationName)
    {
        var response = await _client.CreateOrganization(new CreateOrganizationRequest
        {
            Name = organizationName,
            BackgroundColor = "#123456"
            // some other props
        });
        
        if (!response.IsSuccessStatusCode)
        {
            return Results.Fail(response.Error.Content);
        }
        
        var organizationCode = response.Content.Organization.Code; 
        
        return Results.Ok(organizationCode);
    }
}

Overall, the usage looks like this:

await _client.CreateSomething(new CreateSomethingRequest 
{ 
    SomeProp = "someValue" 
});
await _client.UpdateSomething(new UpdateSomethingRequest 
{ 
    Name = "someName" 
});
await _client.DeleteSomething(someId);
await _client.GetSomething(someId);
await _client.GetSomethings();
await _client.GetSomethings(new GetSomethingsQueryFilter 
{ 
    SortingMethod = SomethingSortingMethod.NameDescending,
    PageSize = 25, 
    NextToken = "125213412-4123-4123-412"
});
Product Compatible and additional computed target framework versions.
.NET net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.0.5-alpha 171 12/8/2023
0.0.4-alpha 120 10/27/2023
0.0.3-alpha 89 10/25/2023
0.0.2-alpha 83 10/24/2023
0.0.1-alpha 78 10/11/2023

Improved DX by converting null collections from API to empty collections in order to avoid null reference exceptions. You may want to remove redundant null checks after this update. Adjusted namespaces for response models (breaking change).