Axowl.Sdk.Korean.Identity.Client 0.1.1

Axowl.Sdk.Korean.Identity.Client

Server-side SDK for checking 한국 본인인증 (PortOne CI/DI) status of EndUsers. The actual verification flow (PortOne popup) runs in the frontend via @axowl/sdk-core JS SDK — this .NET SDK is for backend gating and audit lookups.

Install

dotnet add package Axowl.Sdk.Identity.Client          # JwtBearer first
dotnet add package Axowl.Sdk.Korean.Identity.Client

Quickstart

using Axowl.Sdk.Identity.Client;
using Axowl.Sdk.Korean.Identity.Abstractions.Contracts;
using Axowl.Sdk.Korean.Identity.Client;

var builder = WebApplication.CreateBuilder(args);

// 1) JwtBearer + JWKS (Phase 1.2 SDK)
builder.Services.AddAxowlIdentity(opts =>
{
    opts.OrganizationSlug = "bullmark";
    opts.Audience         = "app_bullmark_main";
    opts.ApiKey           = builder.Configuration["Axowl:ApiKey"]!;
});

// 2) Korean Identity client (this package)
builder.Services.AddAxowlKoreanIdentity(opts =>
{
    opts.ApiKey    = builder.Configuration["Axowl:ApiKey"]!;
    opts.Transport = TransportMode.GrpcWithFallback;
    // These are the defaults — set them only to point somewhere else
    // opts.ServerAddress     = "https://testgrpc.axowl.com";
    // opts.RestServerAddress = "https://testapi.axowl.com";
});

builder.Services.AddAuthorization();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

// 본인인증 게이팅
app.MapPost("/shop/checkout",
    [RequireKoreanIdentity(Purpose = "shop-checkout")]
    () => Results.Ok("ordered"));

// 또는 programmatic check
app.MapGet("/me/identity-status", async (
    IAxowlKoreanIdentityClient korean,
    HttpContext ctx) =>
{
    var bearer = ctx.Request.Headers.Authorization.ToString();
    var token  = bearer.StartsWith("Bearer ") ? bearer[7..] : "";
    var status = await korean.GetStatusAsync(token);
    return Results.Ok(status);
});

app.Run();

API

public interface IAxowlKoreanIdentityClient
{
    Task<KoreanIdentityStatus> GetStatusAsync(
        string token, string? purpose = null, CancellationToken ct = default);

    Task<IReadOnlyList<KoreanIdentityRecord>> ListAsync(
        string token, CancellationToken ct = default);
}

public sealed record KoreanIdentityStatus(
    bool       Verified,
    Guid?      VerificationId,
    string?    Purpose,
    string?    Method,         // Sms / Card / KakaoCert / NaverCert / TelcoPass / GongdongCert
    bool       IsForeigner,
    DateTime?  VerifiedAt);

[RequireKoreanIdentity] attribute

Blocks the endpoint if the user has no active verification matching Purpose (null = any purpose).

Response when blocked:

HTTP 403
Axowl-Korean-Identity-Required: shop-checkout
{
  "error": "korean_identity_required",
  "purpose": "shop-checkout",
  "hint": "Trigger verification via axowl-sdk-core: client.korean.verifyIdentity({ purpose })"
}

Frontend reacts to the Axowl-Korean-Identity-Required header and calls client.korean.verifyIdentity({ purpose }) to launch the PortOne popup.

Verification flow (where does the actual popup happen?)

Step 5 = what this SDK does. Steps 1-4 = JS SDK (@axowl/sdk-core) + Axowl public endpoints (already live).

Configuration reference

public sealed class AxowlKoreanIdentityClientOptions
{
    public string ServerAddress     { get; set; } = "https://testgrpc.axowl.com";
    public string RestServerAddress { get; set; } = "https://testapi.axowl.com";
    public string ApiKey            { get; set; } = "";   // required
    public TransportMode Transport  { get; set; } = TransportMode.Grpc;
}

Related

• Axowl.Sdk.Identity.Client — JwtBearer + JWKS + IAxowlIdentityClient (required prerequisite)
• Axowl.Sdk.Integrity.Client — hash chain / tamper detect
• Frontend SDK guide: docs/sdk-korean-identity.md