Humanos 1.0.2

Humanos SDK for C# / .NET

Official C# SDK for the Humanos API. Provides automatic request signing, webhook verification and decryption, and full API access for credential management.

Features

• Automatic Request Signing - All API requests are signed with HMAC-SHA256
• Webhook Verification - Verify signatures and decrypt encrypted payloads
• Strong Typing - Full type definitions with generated models
• Simple API - Clean interface for all Humanos endpoints

Getting Started

1. Install the SDK

dotnet add package Humanos.

2. Create an Account

Sign up at humanos.id and create your organization.

3. Get Your API Keys

In the Humanos Dashboard, go to Settings > API Keys and copy:

• API Key - Used to authenticate requests
• Signature Secret - Used to sign requests with HMAC-SHA256

4. Get Your Webhook Keys

In the Humanos Dashboard, go to Settings > Webhooks and copy:

• Webhook Signature Secret - Used to verify incoming webhook signatures
• Webhook Encryption Secret - Used to decrypt webhook payloads
• Webhook Encryption Salt - Used alongside the encryption secret

5. Initialize the Client

using Humanos;

var client = new HumanosClient(new HumanosClientConfig
{
    BasePath = "https://api.humanos.id",
    ApiKey = Environment.GetEnvironmentVariable("HUMANOS_API_KEY")!,
    SignatureSecret = Environment.GetEnvironmentVariable("HUMANOS_SIGNATURE_SECRET")!,
});

6. Make Your First API Call

Fetch all your credential requests:

var response = client.Requests.GetRequests();
Console.WriteLine(response.Data);

Usage Examples

Create a Credential Request

Send a credential request to one or more contacts using pre-configured resources:

using Humanos.Generated.Model;

var request = client.Requests.Generate(new GenerateRequestDto(
    contacts: new List<string> { "user@example.com" },
    securityLevel: GenerateRequestDto.SecurityLevelEnum.CONTACT,
    resourcesIds: new List<string> { "your-resource-id" }
));

Console.WriteLine("Request ID: " + request.Id);
Console.WriteLine("Credentials: " + request.Credentials);

You can also use group IDs to include all resources in a group:

var request = client.Requests.Generate(new GenerateRequestDto(
    contacts: new List<string> { "user@example.com" },
    securityLevel: GenerateRequestDto.SecurityLevelEnum.CONTACT,
    groupIds: new List<string> { "your-group-id" }
));

Or provide inline credential data directly:

var request = client.Requests.Generate(new GenerateRequestDto(
    contacts: new List<string> { "user@example.com" },
    securityLevel: GenerateRequestDto.SecurityLevelEnum.CONTACT,
    credentials: new List<CredentialDto>
    {
        new CredentialDto(
            scope: "onboarding",
            type: CredentialDto.TypeEnum.JSON,
            name: "Service Agreement",
            data: new List<MandateDataDto>
            {
                new MandateDataDto(label: "Company", type: "string", value: new MandateDataDtoValue("Acme Corp")),
                new MandateDataDto(label: "Plan", type: "string", value: new MandateDataDtoValue("Enterprise")),
            }
        ),
    }
));

Receive Webhooks

Humanos sends webhook events when credentials are signed, identity checks complete, or OTPs fail. Payloads are encrypted and signed.

The SDK provides Webhooks.ProcessWebhook which handles signature verification and payload decryption automatically:

using Humanos;

var config = new WebhookConfig
{
    SignatureSecret = Environment.GetEnvironmentVariable("HUMANOS_WEBHOOK_SIGNATURE_SECRET")!,
    EncryptionSecret = Environment.GetEnvironmentVariable("HUMANOS_WEBHOOK_ENCRYPTION_SECRET")!,
    EncryptionSalt = Environment.GetEnvironmentVariable("HUMANOS_WEBHOOK_ENCRYPTION_SALT")!,
};

app.MapPost("/webhook", async (HttpContext context) =>
{
    using var reader = new StreamReader(context.Request.Body);
    var rawBody = await reader.ReadToEndAsync();

    var headers = new Dictionary<string, string>
    {
        { "x-signature", context.Request.Headers["x-signature"].ToString() },
        { "x-timestamp", context.Request.Headers["x-timestamp"].ToString() },
    };

    var payload = Webhooks.ProcessWebhook<Dictionary<string, object>>(rawBody, headers, config);

    var eventType = payload["eventType"]?.ToString();
    switch (eventType)
    {
        case "credential":
            Console.WriteLine("Credential signed: " + payload["requestId"]);
            break;
        case "identity":
            Console.WriteLine("Identity verified: " + payload["requestId"]);
            break;
        case "otp.failed":
            Console.WriteLine("OTP failed: " + payload["requestId"]);
            break;
        case "test":
            Console.WriteLine("Test event received");
            break;
    }

    return Results.Ok();
});

For local development, use ngrok to expose your server:

ngrok http 3000

Then set the ngrok URL (e.g. https://xxxx.ngrok-free.app/webhook) as your webhook URL in the Humanos Dashboard under Settings > Webhooks.

API Reference

Resources

// List resources
var resources = client.Resources.GetResources();

// List resource groups
var groups = client.Resources.GetGroups();

Requests

// List requests
var requests = client.Requests.GetRequests();

// Get request details
var detail = client.Requests.GetRequestDetail(requestId);

// Create a credential request
var request = client.Requests.Generate(new GenerateRequestDto(...));

// Cancel a request
client.Requests.CancelRequest(requestId);

// Resend OTP
client.Requests.ResendOtp(requestId, contact: "user@example.com");

Users

using Humanos.Generated.Model;

// Create or update users
var users = client.Users.Create(new List<CreateSubjectDto>
{
    new CreateSubjectDto(
        contact: "user@example.com",
        internalId: "your-internal-id",
        identity: new IdentityDto(
            fullName: "John Doe",
            birth: new DateTime(1990, 1, 1),
            docId: "123456789",
            countryAlpha3: "USA"
        )
    )
});

Credentials

// Get credential by ID
var credential = client.Credentials.GetCredential(credentialId);

// Get credential with PDF
var credential = client.Credentials.GetCredential(credentialId, includePdf: true);

Error Handling

The SDK throws ApiException for failed requests. The exception includes the HTTP status and response body:

using Humanos.Generated.Client;

try
{
    var request = client.Requests.Generate(new GenerateRequestDto(...));
}
catch (ApiException e)
{
    Console.Error.WriteLine($"Status: {e.ErrorCode}");
    Console.Error.WriteLine($"Body: {e.ErrorContent}");
}
catch (Exception e)
{
    Console.Error.WriteLine($"Error: {e.Message}");
}

Documentation

• API Documentation
• Humanos Website

Support

• Email: tech@humanos.tech

License

MIT License - see LICENSE file for details.