Altinn.ApiClients.Dialogporten.ServiceOwner 1.120.1-alpha.1788463247

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

Authorization contexts

An entity with an authorizationContext (a transmission, attachment, action or navigational action) can be granted through a party or resource other than the dialog's own, so its grant is not expressed by the actions claim. Instead the dialog token's e claim lists, for every such entity the end user is authorized for, the entity's id or the tokenRef the service owner supplied on the context. For a request scoped to such an entity, pass the reference and the validation fails unless it is listed:

var result = validator.Validate(dialogToken, dialogId: dialogId, requiredEntityReference: transmissionId.ToString());
// or, when the context was created with a tokenRef:
var result = validator.Validate(dialogToken, dialogId: dialogId, requiredEntityReference: "my-own-reference");

// The listed references are also available directly:
var authorizedEntities = result.ClaimsPrincipal?.GetAuthorizedEntityReferences();

Always supply dialogId when validating an entity reference; token references are scoped to one dialog. A service owner may intentionally assign the same tokenRef to several entities in a dialog. This creates an OR-group: authorization for any member adds the shared reference to e, and a recipient validating that reference cannot distinguish which member was authorized. Only group entities that deliberately share access semantics.

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

Mapping between dialog models

The API uses three parallel dialog model families: Dialog (the GET response), CreateDialog (the POST body) and UpdateDialog (the PUT body). The Features.V1.Mapping namespace provides extension methods to convert between them for read-modify-write and clone flows:

using Altinn.ApiClients.Dialogporten.ServiceOwner.Features.V1.Mapping;

// Fetch a dialog, mutate it and PUT it back:
var dialog = (await client.GetDialog(dialogId)).Content!;
var update = dialog.ToUpdateDialog();
update.Progress = 100;
update.Status = DialogStatusInput.Completed;
await client.UpdateDialog(dialogId, update);

// Clone an existing dialog into a new one (Id/IdempotentKey are dropped by default):
var clone = dialog.ToCreateDialog();

// Pass preserveId: true to carry over Id/IdempotentKey for an idempotent re-create:
var idempotent = dialog.ToCreateDialog(preserveId: true);

// Reuse a create payload as an update, or vice versa:
UpdateDialog asUpdate = createDialog.ToUpdateDialog();
CreateDialog asCreate = updateDialog.ToCreateDialog(); // remember to set ServiceResource and Party

These conversions are intentionally lossy: fields that have no target on the destination model are dropped (for example, identity, party and visibility fields are not part of an UpdateDialog), and read-only server fields on Dialog (revision, counts, contexts, seen-log) cannot be recovered after a round-trip. The output status enum DialogStatus and the input enum DialogStatusInput are mapped by name; the input-only values New and Sent map to NotApplicable and Awaiting respectively via DialogStatusMapping.ToDialogStatus.