Authentication

Pick ApiKeyAuth for non-interactive callers or RefreshableBearerAuth for OAuth-issued tokens.

Pick an auth strategy

The SDK supports two authentication strategies, both implementing IEksoAuth:

Strategy	Use when
ApiKeyAuth	Server-to-server, agents, CI runners, anything headless. Static credentials.
RefreshableBearerAuth	You already have an OAuth token pair (e.g. obtained via the CLI’s device-flow login or the web app’s auth-code grant). Auto-refreshes on expiry.

You only ever pass one of these to EksoClientOptions.Auth.

ApiKeyAuth

API keys are minted via the admin surface (POST /api/admin/api-key, or ekso api-key create --name "..." from the CLI). The response contains the raw key (ek_live_...) exactly once; capture it immediately and store somewhere safe.

using Ekso.Sdk;
using Ekso.Sdk.Authentication;

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

Properties:

• The key is sent as a Bearer token on every request.
• It carries the permissions of the user who minted it.
• It does not expire on a timer (unless ExpiresAt was set at mint time). Rotate on a policy.
• The backend stamps API-key requests with Client=Sdk — see CLI/SDK marker.

Don’t:

• Embed long-lived keys in client-side code, mobile binaries, or browser-shipped JS.
• Commit keys to source control. Use a secrets manager (KeyVault, AWS Secrets Manager, env-var injection from CI).

RefreshableBearerAuth

Use this when you’ve obtained an access + refresh token pair from an interactive flow (typically OAuth 2.0 device code or authorization-code-with-PKCE).

using Ekso.Sdk;
using Ekso.Sdk.Authentication;

var auth = new RefreshableBearerAuth(
    accessToken: stored.AccessToken,
    refreshToken: stored.RefreshToken,
    tokenEndpoint: new Uri("https://ekso.acme.com/token"),
    clientId: stored.ClientId,
    expiresAt: stored.ExpiresAt);

// Persist rotations so the next process picks up the rotated refresh token.
auth.TokensRefreshed += (_, e) =>
{
    SaveCredentials(new StoredCredentials
    {
        AccessToken = e.AccessToken,
        RefreshToken = e.RefreshToken,
        ExpiresAt = e.ExpiresAt,
    });
};

var client = new EksoClient(new EksoClientOptions
{
    BaseUrl = "https://ekso.acme.com",
    Auth = auth,
});

Properties:

• The SDK transparently exchanges the refresh token for a new access + refresh pair when the access token nears expiry.
• The TokensRefreshed event fires after each rotation so you can persist the new pair. Without this hook, the next process invocation would try to refresh with a token the backend has already invalidated and trigger family-rotation replay detection.
• Device-flow tokens carry Client=Cli; webapp authorization-code tokens carry no client claim (treated as Web at the read site).

Local development

For local development, point the client at your dev install:

var client = new EksoClient(new EksoClientOptions
{
    BaseUrl = "https://devinc.localhost:7070",
    Auth = new ApiKeyAuth(localKey),
});

BaseUrl is required — there is no default. Self-host: this is whatever PublicUrl you set during your install’s /startup wizard.

Logging out / revoking

For ApiKeyAuth: revoke via the admin surface (POST /api/admin/api-key/{id}/revoke or ekso api-key delete <id>). The key stops working immediately on subsequent calls.

For RefreshableBearerAuth: there is no client-side “logout” — discard the stored token pair and the user’s session is effectively gone. The refresh token expires server-side on a sliding window of inactivity.

Token-store integration

The CLI persists RefreshableBearerAuth tokens to a per-install credential store on disk, keyed on the install URL (see EksoClientFactory in Ekso.Cli). If you’re embedding the SDK in your own app, design your token store the same way — keyed by (BaseUrl, ClientId) so a developer with multiple installs (their own + a customer’s) doesn’t get cross-install token bleed.

Next steps

• Quickstart — your first authenticated call.
• Error handling — what to expect when auth fails.
• CLI/SDK marker — server-side gating semantics that depend on which auth you chose.