ArconQ Management SDK

The ArconQ Management SDK (ArconQ.SDK.Management) lets your applications administer the ArconQ platform programmatically. In ArconQ 1.3.0 it provides an identity management client for managing users, roles and groups — the same entities you can manage from the Administration area of the ArconQ UI.

Use it to automate onboarding, keep ArconQ users, roles and group memberships in sync with an external system, or provision access from within your own app.

Installation

Add the ArconQ.SDK.Management NuGet package to your project. It targets .NET 8, 9 and 10 and depends on the ArconQ SDK.

dotnet add package ArconQ.SDK.Management

Registration

Register the identity management client with AddArconQIdentityManagementClient, passing the credentials of an external client:

builder.Services.AddArconQIdentityManagementClient(
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET");

This registers IIdentityManagementClient and the secure HTTP client infrastructure it needs — you do not have to call AddSecureHttpClients separately. The client authenticates against the ArconQ identity provider (Keycloak) using the client-credentials flow and calls the ArconQ identity service in-cluster, so it is intended to run from an app deployed on your ArconQ instance.

caution

Managing users, roles and groups is an administrative operation. The external client whose credentials you supply must have sufficient privileges (the admin role). Store the client secret securely — for example through App configurations — rather than hardcoding it.

Inject IIdentityManagementClient wherever you need it:

public class AccessProvisioningService
{
    private readonly IIdentityManagementClient _identityManagementClient;

    public AccessProvisioningService(IIdentityManagementClient identityManagementClient)
    {
        _identityManagementClient = identityManagementClient;
    }
}

Managing users

// Get all users (each includes its assigned roles and groups).
List<UserResponse> users = await _identityManagementClient.GetUsersAsync();

// Get a single user by id, or null when no such user exists.
UserResponse? user = await _identityManagementClient.GetUserByIdAsync(userId);

// Update a user, replacing its role and group assignments.
await _identityManagementClient.UpdateUserAsync(new UpdateUserRequest(
    UserId: user!.Id,
    Username: user.Username,
    FirstName: "John",
    LastName: "Doe",
    Email: "john.doe@example.com",
    RoleIds: [operatorRoleId],   // full set of roles after the update
    GroupIds: null));            // null leaves group memberships unchanged

Method	Description
GetUsersAsync(Guid? userId = null)	Returns all users, or a single-item list when a userId is supplied. Each user includes its assigned roles and groups.
GetUserByIdAsync(Guid userId)	Returns a single user by id, or null when no user with that id exists.
UpdateUserAsync(UpdateUserRequest request)	Updates a user's details, role assignments and group memberships.

When updating a user, RoleIds and GroupIds are treated as full sets and replace the current assignments. Passing null for either leaves that set of assignments unchanged. A user's password is never affected by an update.

Managing roles

// List all roles.
List<RoleResponse> roles = await _identity.GetRolesAsync();

// Create a role.
await _identity.CreateRoleAsync(new CreateRoleRequest(
    Name: "wes-operator",
    Description: "WES line operator"));

// Delete a role by id.
await _identity.DeleteRoleAsync(roleId);

Method	Description
GetRolesAsync()	Returns all roles.
CreateRoleAsync(CreateRoleRequest request)	Creates a role.
DeleteRoleAsync(Guid roleId)	Deletes the role with the given id.

Role names must consist of lowercase letters, digits and dashes, and be at most 50 characters long. Deleting a role removes it from every user and group it was assigned to. See Role management for how roles behave in ArconQ, including the built-in admin and developer roles.

Managing groups

// List all groups (each includes its assigned roles).
List<GroupResponse> groups = await _identity.GetGroupsAsync();

// Update a group, replacing its role assignments.
await _identity.UpdateGroupAsync(new UpdateGroupRequest(
    GroupId: group.Id,
    Name: "operators",
    Description: "Line operators",
    RoleIds: [operatorRoleId]));   // full set of roles; null leaves them unchanged

Method	Description
GetGroupsAsync()	Returns all groups, each including its assigned roles.
UpdateGroupAsync(UpdateGroupRequest request)	Updates a group's details and role assignments.

As with users, a group's RoleIds are treated as a full set and replace the current assignments; passing null leaves them unchanged. Group names follow the same rules as role names (lowercase letters, digits and dashes, up to 50 characters).

Data types

public record UserResponse(
    Guid Id,
    string Username,
    string FirstName,
    string LastName,
    string Email,
    bool IsBuiltIn,                     // true for built-in accounts that cannot be removed
    ReadOnlyMemory<byte>? ProfileImage,
    List<RoleResponse> Roles,           // roles assigned directly to the user
    List<GroupResponse> Groups);        // groups the user is a member of

public record UpdateUserRequest(
    Guid UserId,
    string Username,
    string FirstName,
    string LastName,
    string Email,
    List<Guid>? RoleIds,                // null → leave role assignments unchanged
    List<Guid>? GroupIds);              // null → leave group memberships unchanged

public record RoleResponse(
    Guid Id,
    string Name,
    string? Description);

public record CreateRoleRequest(
    string Name,
    string? Description);

public record GroupResponse(
    Guid Id,
    string Name,
    string? Description,
    List<RoleResponse> Roles);          // roles assigned to the group

public record UpdateGroupRequest(
    Guid GroupId,
    string Name,
    string? Description,
    List<Guid>? RoleIds);               // null → leave role assignments unchanged