Ekso.Sdk 2.2.0

Ekso.Sdk

Official C# SDK for the Ekso API. Auto-generated from the Ekso OpenAPI spec via Kiota, with thin hand-polish on top for auth, pagination, batch, and typed errors.

Pairs with Ekso.Cli — a dotnet tool that wraps every method this SDK exposes.

Install

dotnet add package Ekso.Sdk

Quick start

using Ekso.Sdk;

var client = new EksoClient(new EksoClientOptions {
    Tenant = "acme",
    Auth = new ApiKeyAuth(Environment.GetEnvironmentVariable("EKSO_API_KEY")!),
});

// Generated URL-driven surface:
var clocks = await client.Api.Clock.GetAsync();
var clock  = await client.Api.Clock["clock-123"].GetAsync();
var items  = await client.Api.Item.GetAsync();

The client surface mirrors the URL hierarchy: /api/{resource}/{id}/{sub} becomes client.Api.Resource[id].Sub.MethodAsync(). Method names follow HTTP verb convention (GetAsync, PostAsync, PutAsync, PatchAsync, DeleteAsync).

Auth strategies

API key — for agents, CI, headless services

var client = new EksoClient(new EksoClientOptions {
    Tenant = "acme",
    Auth = new ApiKeyAuth(Environment.GetEnvironmentVariable("EKSO_API_KEY")!),
});

A super-admin in your tenant mints keys via POST /api/admin/api-key. The raw key is returned exactly once at issuance — capture it immediately. The server only keeps a SHA-256 hash; there is no recovery path if you lose it.

OAuth device flow — for CLIs and human-attended servers

using Ekso.Sdk;

var client = await EksoClient.LoginDeviceAsync(
    tenant: "acme",
    clientId: "ekso-cli",
    onPrompt: prompt =>
    {
        Console.WriteLine($"Open {prompt.VerificationUriComplete}");
        Console.WriteLine($"Or enter code: {prompt.UserCode} at {prompt.VerificationUri}");
    });

// User signs in on the browser; the SDK polls until approved, then returns.
var clocks = await client.Api.Clock.GetAsync();

Tokens refresh transparently on 401 — the SDK silently swaps the access token using the stored refresh token and retries the original request. Hook the TokensRefreshed event on the auth strategy to persist rotated tokens between sessions:

var auth = new RefreshableBearerAuth(savedAccess, savedRefresh, tokenEndpoint, clientId);
auth.TokensRefreshed += (_, e) => SaveTokens(e.AccessToken, e.RefreshToken, e.ExpiresAt);
var client = new EksoClient(new EksoClientOptions { Tenant = "acme", Auth = auth });

OAuth PKCE — for .NET desktop / Blazor clients hosting their own redirect

var pkce = EksoClient.BuildPkceAuthorizeUri(
    tenant: "acme",
    clientId: "my-app",
    redirectUri: new Uri("http://localhost:5000/callback"));

// Open pkce.AuthorizeUri in a browser, capture the `code` returned to your callback...
var client = await EksoClient.ExchangePkceCodeAsync(
    tenant: "acme",
    clientId: "my-app",
    redirectUri: new Uri("http://localhost:5000/callback"),
    code: receivedCode,
    codeVerifier: pkce.CodeVerifier);

The SDK does not open browsers or run redirect listeners — those are caller concerns. We provide the OAuth primitives.

Pagination

using Ekso.Sdk.Pagination;

await foreach (var item in PagedAsyncEnumerable.Create<DataItem>(
    (page, ct) => FetchItemPage(client, page, ct)))
{
    Process(item);
}

Lazy by default — the first network call is deferred until the consumer reads the first item. Cancellation is honoured between pages and items, so cancelling mid-stream releases the connection promptly.

Parallel batching

using Ekso.Sdk.Batch;

var batch = await client.BatchAsync<int>(
[
    (c, ct) => c.Api.Clock.GetAsync(cancellationToken: ct).ContinueWith(t => t.Result.Count),
    (c, ct) => c.Api.Item.GetAsync(cancellationToken: ct).ContinueWith(t => t.Result.Items.Count),
]);

if (batch.AllSucceeded) { /* ... */ }
foreach (var error in batch.Errors) { /* ... */ }

Per-op error capture means a single failure doesn't tank the whole batch.

Typed exceptions

Catch the SDK's exception hierarchy for structured error handling:

try
{
    await client.Api.Item.PostAsync(cmd);
}
catch (EksoRateLimitException ex)
{
    await Task.Delay(ex.RetryAfter);
    // retry...
}
catch (EksoAuthException ex) when (ex.Reason == AuthFailureReason.Expired)
{
    // refresh token expired — rerun LoginDeviceAsync / LoginPkceAsync
}
catch (EksoNetworkException ex)
{
    // transient — retry with backoff
}

Available subclasses: EksoApiException, EksoAuthException, EksoRateLimitException, EksoValidationException, EksoNetworkException — all inherit from EksoException.

License

MIT.