Altinn.ApiClients.Dialogporten.ServiceOwner 1.119.0-alpha.1786973049

Altinn.ApiClients.Dialogporten.ServiceOwner

.NET SDK for the Dialogporten ServiceOwner API. Provides a typed HTTP client for creating and managing dialogs on behalf of a service owner, backed by Maskinporten authentication and automatic EdDSA key caching for dialog token validation.

Sample projects are available at https://github.com/Altinn/dialogporten-samples.

Installation

dotnet add package Altinn.ApiClients.Dialogporten.ServiceOwner

Targets net8.0, net9.0, and net10.0.

Setup

Register the client in your DI container using AddDialogportenClient. The BaseUri must point to the Dialogporten root, excluding /api/v....

Built-in Maskinporten authentication

Provide Maskinporten settings and the SDK handles token acquisition automatically. The primary scope is digdir:dialogporten.serviceprovider; list/search operations also require digdir:dialogporten.serviceprovider.search.

builder.Services.AddDialogportenClient(options =>
{
    options.BaseUri = "https://platform.altinn.no/dialogporten";
    options.Maskinporten = new MaskinportenSettings
    {
        Authority = "https://maskinporten.no/",
        ClientId = "your-client-id",
        Scope = "digdir:dialogporten.serviceprovider digdir:dialogporten.serviceprovider.search",
        // Supply either EncodedJwk or a certificate
        EncodedJwk = "..."
    };
});

Custom authentication

If you manage Maskinporten tokens yourself (e.g. via a shared client definition), use the overload that accepts an IHttpClientBuilder delegate:

builder.Services.AddDialogportenClient(
    options => options.BaseUri = "https://platform.altinn.no/dialogporten",
    httpClientBuilder => httpClientBuilder.AddMaskinportenHttpMessageHandler<MyClientDefinition>("my-key")
);

Using the client

Inject IServiceOwnerApi and call methods on the V1 property:

public class MyService(IServiceOwnerApi dialogporten)
{
    public async Task<string> CreateDialogAsync(CreateDialog dto, CancellationToken ct)
    {
        var response = await dialogporten.V1.CreateDialog(dto, ct);

        if (!response.IsSuccessStatusCode)
            throw new Exception($"Failed: {response.StatusCode}");

        // response.Content contains the new dialog ID
        return response.Content!;
    }
}

All methods return IApiResponse<T> (or IApiResponse for void responses) from Refit, giving you access to the status code, headers, and deserialized content.

Available operations

Dialogs (CRUD)

Search filter highlights (SearchDialogsQueryParams):

• ServiceResource, Party, EndUserId — filter by resource, receiving party, or a specific end user
• Status — New, InProgress, Waiting, Signing, Cancelled, Completed
• Deleted — Include, Exclude (default), or Only
• SystemLabel, ServiceOwnerLabels — filter by system or custom service-owner labels (prefix matching with * supported)
• CreatedAfter/Before, UpdatedAfter/Before, ContentUpdatedAfter/Before, DueAfter/Before, VisibleAfter/Before
• IsContentSeen — filter by seen/unseen content
• Search / SearchLanguageCode — free-text fuzzy search
• ContinuationToken, Limit (1–1000, default 100)

Dates must include an explicit time zone, e.g. 2024-01-15T10:00:00Z.

Transmissions

Activities

Seen log

Service owner labels

System labels (end user context)

Other

Optimistic concurrency

Write operations accept an optional ifMatch parameter (maps to If-Match header). Pass the Revision GUID from a prior GetDialog response to prevent overwriting concurrent changes. A mismatched revision returns 412 Precondition Failed.

Dialog token validation

Dialogporten issues short-lived EdDSA-signed dialog tokens when an end user accesses a dialog. Your backend can validate these tokens using the injected IDialogTokenValidator:

public class MyController(IDialogTokenValidator validator)
{
    [HttpGet("resource/{dialogId}")]
    public IActionResult Get(Guid dialogId, [FromHeader] string dialogToken)
    {
        var result = validator.Validate(dialogToken, dialogId: dialogId, requiredActions: ["read"]);

        if (!result.IsValid)
            return Forbid();

        // result.ClaimsPrincipal is non-null here
        return Ok();
    }
}

The validator caches public keys fetched from the Dialogporten .well-known endpoint (via a background hosted service). By default it throws on startup if keys cannot be fetched; set ThrowOnPublicKeyFetchInit = false in DialogportenSettings to make startup tolerant of transient failures.

DialogTokenValidationParameters lets you override defaults globally or per-call:

// Per-call override with extra clock skew
var result = validator.Validate(token, options: new DialogTokenValidationParameters
{
    ClockSkew = TimeSpan.FromSeconds(30)
});

Settings reference

{
  "Dialogporten": {
    "BaseUri": "https://platform.altinn.no/dialogporten",
    "ThrowOnPublicKeyFetchInit": true,
    "Maskinporten": {
      "Authority": "https://maskinporten.no/",
      "ClientId": "your-client-id",
      "Scope": "digdir:dialogporten.serviceprovider digdir:dialogporten.serviceprovider.search",
      "EncodedJwk": "..."
    }
  }
}

Bind and register:

var settings = builder.Configuration
    .GetSection("Dialogporten")
    .Get<DialogportenSettings>()!;

builder.Services.AddDialogportenClient(settings);