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

# Installation

> Install, authenticate, and configure the official VZaps .NET SDK

The official VZaps .NET SDK wraps authentication, HTTP calls, required headers, realtime events, and the main public API resources.

Use it in ASP.NET Core APIs, Workers, Windows/Linux services, CLIs, and server-to-server automations.

## Requirements

| Resource    | Version                     |
| ----------- | --------------------------- |
| .NET        | .NET Standard 2.0 or higher |
| Recommended | .NET 8 or higher            |

## Install

```bash theme={null}
dotnet add package VZaps.SDK
```

## Create the client

```csharp theme={null}
using VZaps;

using var client = new VZapsClient(new VZapsClientOptions
{
    ClientToken = "your-client-token",
    ClientSecret = "your-client-secret",
});
```

With ASP.NET Core or Worker, register the client in the container:

```csharp theme={null}
builder.Services.AddVZapsClient(options =>
{
    options.ClientToken = builder.Configuration["VZaps:ClientToken"];
    options.ClientSecret = builder.Configuration["VZaps:ClientSecret"];
});
```

Then inject `VZapsClient` into handlers, controllers, or hosted services.

## Credentials

| Credential      | Where to use         | Description                                          |
| --------------- | -------------------- | ---------------------------------------------------- |
| `ClientToken`   | `VZapsClientOptions` | Account client token, also sent as `X-Client-Token`. |
| `ClientSecret`  | `VZapsClientOptions` | Secret used by the SDK to obtain and refresh JWTs.   |
| `InstanceToken` | Each instance call   | Instance token, sent as `X-Instance-Token`.          |

Do not expose `ClientSecret` or `InstanceToken` in public front ends.

## Automatic authentication

The SDK obtains a JWT with `ClientToken` and `ClientSecret`, caches it in memory, and refreshes it before expiry.

```csharp theme={null}
var accessToken = await client.Auth.GetAccessTokenAsync();
```

## Client options

| Option             | Default     | Use                               |
| ------------------ | ----------- | --------------------------------- |
| `Timeout`          | 30 seconds  | HTTP timeout.                     |
| `TokenRefreshSkew` | 60 seconds  | Refresh JWT before actual expiry. |
| `UserAgent`        | SDK default | HTTP `User-Agent` header.         |

## Environment variables

```bash theme={null}
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=your-instance-token
```

## Typing responses

Examples use `object` or `JsonElement` when the response can vary. In production, you can create your own DTOs and pass them as `TResponse`.

```csharp theme={null}
var response = await client.Instances.ListAsync<JsonElement>(new InstanceListRequest
{
    Page = 1,
    PageSize = 20,
});
```

## Next steps

* Follow the [Starter Guide](/en/sdk/dotnet/starter-guide).
* See [Messages](/en/sdk/dotnet/messages) for send methods.
* See [Realtime](/en/sdk/dotnet/realtime) for WebSocket subscriptions.