> ## Documentation Index
> Fetch the complete documentation index at: https://ekso.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Ekso SDK

> The official C# SDK for Ekso. Type-safe access to every public API operation, with auth, retry, and error handling built in.

## Overview

`Ekso.Sdk` is the official C# client library for Ekso, distributed on NuGet as `Ekso.Sdk`. It exposes every public API operation as a typed, async method on a single `EksoClient` — from `client.Api.Item.PostAsync(...)` to `client.Api.Field.List.Data.PutAsync(...)`.

Reach for the SDK when you're building:

* A .NET application that integrates with Ekso (web app, background service, console tool).
* An agent or workflow runner that needs typed responses, not raw JSON.
* A tool that benefits from compile-time guarantees against the Ekso schema.

For terminal automation and scripting, prefer the [CLI](/cli/overview) — the same operations, shell-shaped.

## What's in the package

`Ekso.Sdk` ships:

* `EksoClient` — the typed root of the API surface. Internally backed by [Kiota](https://github.com/microsoft/kiota) generated request builders.
* `EksoClientOptions` — configuration record (`Tenant`, `Auth`, `BaseUrl`).
* Two auth strategies: `ApiKeyAuth` (static keys) and `RefreshableBearerAuth` (OAuth tokens with auto-refresh).
* A typed exception hierarchy (`EksoAuthException`, `EksoRateLimitException`, `EksoValidationException`, `EksoNetworkException`, `EksoApiException`).
* Generated model types for every request/response shape — `DataItem`, `DataFieldList`, `FieldCollection`, etc.

The SDK is regenerated from the canonical OpenAPI spec on every backend release; the typed surface is always in sync with what the API actually serves.

## Target framework

The SDK targets **.NET 10**. It depends on Kiota's runtime libraries (`Microsoft.Kiota.Abstractions`, `Microsoft.Kiota.Http.HttpClientLibrary`, JSON/Form/Multipart/Text serializers).

## Quick taste

```csharp theme={null}
using Ekso.Sdk;
using Ekso.Sdk.Authentication;

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

// List items via the typed surface
var page = await client.Api.Item.List.PostAsync(new ItemListRequest { /* filters */ });

foreach (var item in page!.Data!)
{
    Console.WriteLine($"{item.Key}: {item.Name}");
}
```

## Authentication paths

Two strategies, picked based on caller shape:

* **`ApiKeyAuth`** — non-interactive. Pass a minted API key (`ek_...`); every request carries it as a Bearer token. Best for server-to-server, agents, CI.
* **`RefreshableBearerAuth`** — interactive. Pass an access + refresh token pair (typically obtained via OAuth device flow); the SDK auto-refreshes and fires a `TokensRefreshed` event so you can persist the rotated pair.

Both authenticate as a CLI/SDK client (`Client=Sdk` for API keys, `Client=Cli` for device-flow tokens). The backend uses that marker to gate operations that should not be scriptable — e.g. system field updates are rejected from SDK callers but allowed from the webapp. See [CLI/SDK marker](/sdk/cli-sdk-marker).

## Where to next

* **[Installation](/sdk/installation)** — add the package and verify the dependency.
* **[Authentication](/sdk/authentication)** — set up `ApiKeyAuth` or `RefreshableBearerAuth`.
* **[Quickstart](/sdk/quickstart)** — your first authenticated call.
* **[Error handling](/sdk/error-handling)** — the exception hierarchy and how to react to each shape.
* **[CLI/SDK marker](/sdk/cli-sdk-marker)** — what the `Client=Sdk` claim means at the read side.
* **[API Reference](/api-reference/introduction)** — the HTTP surface every typed method calls.