Veracity.Core.Api.V4.Privileged 1.0.20251203.3

Veracity Core API V4 Privileged

A .NET library for interacting with the Veracity Graph API with privileged access, enabling advanced user management operations through Server-Sent Events (SSE).

Overview

The Veracity.Core.Api.V4.Privileged package provides privileged access to the Veracity platform APIs, allowing you to perform administrative operation, creating user with licenses, rights, and group memberships in a tenant. This package is restricted and intended for use by the Veracity Platform and select partners. Client needs to be approved and set up as Administrator of the tenant by Veracity.

Features

• Privileged User Creation: Create users with full configuration including licenses, rights, and group memberships
• Server-Sent Events (SSE): Real-time progress updates during user creation operations
• Client Credentials Authentication: Secure authentication using OAuth client credentials flow
• Easy Integration: Simple dependency injection setup with .NET service collections

Installation

Install the package via NuGet Package Manager:

dotnet add package Veracity.Core.Api.V4.Privileged

Or via Package Manager Console:

Install-Package Veracity.Core.Api.V4.Privileged

Prerequisites

• .NET 8.0 or higher
• Valid Veracity application credentials (Client ID and Client Secret)
• Privileged access permissions to Veracity Graph API

Configuration

1. appsettings.json

Add the following configuration to your appsettings.json:

{
  "Veracity": {
    "ClientId": "your-client-id",
    "ClientSecret": "your-client-secret",
    "PrivilegedSubscriptionKey": "your-privileged-subscription-key",
    "PrivilegedScope": "https://dnvglb2cprod.onmicrosoft.com/dfc0f96d-1c85-4334-a600-703a89a32a4c/.default"
    "VeracityGraphPrivilegedBaseUrl": "https://api.veracity.com/veracity/privileged/graph/v4"
  }
}

Note: For production environments, use the production URLs instead of test URLs.

Usage

Basic Setup

using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Veracity.Common.Authentication;
using Veracity.Core.Api.V4.Business.SSE;
using Veracity.Core.Api.V4.Privileged;

// Load configuration
var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

// Get credentials from configuration
var clientId = "your-client-id";
var clientSecret = "your-client-secret";

// Configure services
var services = new ServiceCollection()
    .AddVeracity(configuration)
    .AddVeracityGraphApi()
    .AddVeracityGraphApiPrivileged(clientId, clientSecret);

Creating a User with SSE

Create a handler class to encapsulate the user creation logic with dependency injection:

class MyHandler
{
    private readonly ICreateUserSseClient _sseClient;

    public MyHandler(ICreateUserSseClient sseClient)
    {
        _sseClient = sseClient;
    }

    public async Task CreateUser()
    {
        var tenantId = "be0c84cb-7a4a-4114-aa17-9c0224b084cf";
        var payload = new CreateUserPayload
        {
            // Configure your user payload here. Need to specify Email or UserId.
            // Include licenses, rights, and group memberships as needed
            Email = "someemail@example.com",
            //UserId = new Guid("d290f1ee-6c54-4b01-90e6-d701748f0851"),
            Applications =
            [
                new License { ApplicationId = new Guid("8898dbf9-9d35-4e4a-88fe-7de35e34c6fb"), AccessLevel = "reader" }
            ],
        };

        await _sseClient.CreateUser(tenantId, payload, EventHandler);

        // Event handler to process SSE updates
        Task EventHandler(StageResult<CreateUserResponse> result, int stage)
        {
            Console.WriteLine($"Stage {stage}: {result.Message}");

            if (result.IsComplete)
            {
                Console.WriteLine("User creation completed successfully!");
                Console.WriteLine($"Profile ID: {result.Data?.ProfileId}");
            }

            return Task.CompletedTask;
        }
    }
}

Service Collection Extensions

AddVeracityGraphApiPrivileged

Registers all required services for privileged Veracity Graph API access.

public static IServiceCollection AddVeracityGraphApiPrivileged(
    this IServiceCollection services, 
    string clientId, 
    string clientSecret, 
    string baseUrl = null)

Parameters:

• clientId: Your Veracity application client ID
• clientSecret: Your Veracity application client secret
• baseUrl: (Optional) The base URL of the privileged API. If not provided, reads from configuration key veracityGraphPrivilegedBaseUrl

Key Interfaces

ICreateUserSseClient

Main interface for creating users with Server-Sent Events support.

public interface ICreateUserSseClient
{
    Task CreateUser(
        string tenantId, 
        CreateUserPayload body, 
        Func<StageResult<CreateUserResponse>, int, Task>? eventHandler);
}

Error Handling

Handling Server-Sent Event Errors

Since user creation is a multi-stage process using Server-Sent Events (SSE), you must check the StageResult response for each stage to detect and handle errors appropriately. The event handler receives real-time updates for each stage of the operation.

Important: Errors can occur at any stage of the process (creating user, adding licenses, adding to groups, etc.). Always check the IsFailed and StatusCode properties in your event handler.

Task EventHandler(StageResult<CreateUserResponse> result, int stage)
{
    Console.WriteLine($"Stage {stage}/{result.TotalStages}: {result.Message}");
    Console.WriteLine($"Payload Type: {result.PayloadType}");
    Console.WriteLine($"Retries: {result.NumberOfRetries}");

    // Check if the current stage failed
    if (result.IsFailed)
    {
        Console.Error.WriteLine($"ERROR at stage {stage}:");
        Console.Error.WriteLine($"Status Code: {result.StatusCode}");
        Console.Error.WriteLine($"Error Message: {result.Message}");
        
        // Handle specific error codes
        switch (result.StatusCode)
        {
            case 404:
                Console.Error.WriteLine("Resource not found - verify tenant ID and resource IDs");
                break;
            case 409:
                Console.Error.WriteLine("Conflict - user or resource may already exist");
                break;
            case 403:
                Console.Error.WriteLine("Forbidden - check client credentials and permissions");
                break;
            case 500:
                Console.Error.WriteLine("Internal server error - contact support if this persists");
                break;
            default:
                Console.Error.WriteLine($"Error code {result.StatusCode} occurred");
                break;
        }
        
        // Optionally, take corrective action or log for monitoring
        // Note: The process may still continue or complete depending on the error
    }

    // Check if the process is complete
    if (result.IsComplete)
    {
        if (result.IsFailed)
        {
            Console.Error.WriteLine("User creation process completed with errors!");
        }
        else
        {
            Console.WriteLine("User creation completed successfully!");
            Console.WriteLine($"Profile ID: {result.Data?.ProfileId}");
            Console.WriteLine($"User ID: {result.Data?.UserId}");
        }
    }

    return Task.CompletedTask;
}

Best Practices for Error Handling

1. Check Every Stage: Examine the StageResult in your event handler for each stage of the process.

2. Monitor Status Codes: Use the StatusCode property to identify the type of error:

   • 404 - Resource not found (invalid tenant ID, application ID, etc.)
   • 409 - Conflict (user/license already exists)
   • 403 - Forbidden (insufficient permissions)
   • 500 - Internal server error

3. Track Progress: Use Stage and TotalStages properties to monitor progress and identify where failures occur.

4. Handle Partial Failures: The user creation process may partially succeed (e.g., user created but license addition failed). Check the Data property to see what was completed.

5. Log for Diagnostics: Capture Message, PayloadType, and NumberOfRetries for troubleshooting.

Security Considerations

• Never commit secrets: Store client secrets securely using Azure Key Vault, environment variables, or user secrets
• Use HTTPS: Always use HTTPS endpoints in production
• Rotate credentials: Regularly rotate client secrets
• Limit scope: Only request the minimum required permissions

Support

For issues, questions, or feature requests, please contact the Veracity Platform team.

License

This package is proprietary and restricted to authorized Veracity partners only.

Additional Resources

• Veracity Developer Portal

Note: This is a privileged API package. Ensure you have the necessary permissions and approvals before using it in your applications.