KindeManagementApiClient 0.0.5-alpha

Kinde management API SDK for .NET

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"
});