> For the complete documentation index, see [llms.txt](https://docs.pal.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pal.aic.io/foundations/configuration.md).

# Configuration

PAL.NET configuration has two layers: PAL.NET runtime options and the Foundation host configuration pipeline. Direct SDK consumers can construct `PalantirClientOptions`; Foundation hosts normally bind the `Palantir` section and call `RegisterPlatformCoreServices`.

## Direct runtime options

```csharp
var options = new PalantirClientOptions
{
    BaseAddress = new Uri("https://customer.palantircloud.com/"),
    ApiVersion = "v2",
    RequestTimeout = TimeSpan.FromSeconds(100),
    MaxRetries = 5,
    MaxRetryDelay = TimeSpan.FromSeconds(30),
    EnableRetryJitter = true,
    MaxBufferedResponseBytes = 16 * 1024 * 1024,
    DefaultScopes = ["api:read"],
    EnablePayloadLogging = false
};

options.Validate();
```

Validation is local and fail-fast:

| Option                     | Rule                                                        |
| -------------------------- | ----------------------------------------------------------- |
| `BaseAddress`              | Absolute HTTPS URI.                                         |
| `ApiVersion`               | Non-empty path segment without `/`.                         |
| `RequestTimeout`           | Positive.                                                   |
| `MaxRetries`               | `0` through `10`; counts retries after the initial request. |
| `MaxRetryDelay`            | `0` through 5 minutes.                                      |
| `MaxBufferedResponseBytes` | 4 KiB through 256 MiB.                                      |
| `DefaultScopes`            | No empty scope values.                                      |

## `appsettings.json` shape

```json
{
  "Palantir": {
    "BaseAddress": "https://customer.palantircloud.com/",
    "ApiVersion": "v2",
    "RequestTimeout": "00:01:40",
    "MaxRetries": 5,
    "MaxRetryDelay": "00:00:30",
    "EnableRetryJitter": true,
    "MaxBufferedResponseBytes": 16777216,
    "DefaultScopes": [ "api:read" ],
    "EnablePayloadLogging": false,
    "ClientCredentials": {
      "TokenEndpoint": "https://customer.palantircloud.com/oauth2/token",
      "ClientId": "resolved-by-secret-provider",
      "ClientSecret": "resolved-by-secret-provider"
    },
    "License": {
      "LicenseFilePath": "C:/ProgramData/AIC/PAL.NET/license.json",
      "PublicKeyPem": "resolved-by-secret-provider",
      "ProductId": "PAL.NET"
    }
  }
}
```

{% hint style="warning" %}
Do not commit client secrets, private keys, entitlement files, or production public-key material when the deployment policy treats them as secret-backed configuration. Use the configured Foundation/Foundry provider or deployment secret store.
{% endhint %}

## Foundation loading order

`ConfigureFoundationHost(args)` clears the framework defaults and loads sources in this order, with later values winning:

{% stepper %}
{% step %}

### `appsettings.json`

{% endstep %}

{% step %}

### Optional `PAL.{environment}.json` compatibility overlay

{% endstep %}

{% step %}

### Environment-specific settings

`settings.{environment}.enc` when present, otherwise optional `appsettings.{Environment}.json`.
{% endstep %}

{% step %}

### User secrets

User secrets in Local or Development.
{% endstep %}

{% step %}

### Environment variables

{% endstep %}

{% step %}

### Command-line arguments

{% endstep %}
{% endstepper %}

The environment is taken from `ASPNETCORE_ENVIRONMENT`, then `DOTNET_ENVIRONMENT`, and defaults to `Production`. Files are loaded from `AppContext.BaseDirectory` unless a base directory is provided.

```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Configuration.ConfigureFoundationHost(args);
```

## Encrypted settings

Foundation encrypted settings use AES-256-GCM. Set `AIC_FOUNDATION_CONFIG_KEY` to a Base64-encoded 32-byte key in deployment. Local and Development can use environment-specific .NET user secrets:

```powershell
$keyBytes = [Security.Cryptography.RandomNumberGenerator]::GetBytes(32)
$key = [Convert]::ToBase64String($keyBytes)
dotnet user-secrets set "AIC_FOUNDATION_CONFIG_KEYS:Development" $key `
  --project src/PAL.Core.Infrastructure.Dependencies.Configuration
[Security.Cryptography.CryptographicOperations]::ZeroMemory($keyBytes)
$key = $null
```

{% hint style="warning" %}
Production requires the process environment key. The loader rejects missing, malformed, wrong-length, or legacy unauthenticated encryption keys.
{% endhint %}

## Serialisation limits

Foundation shared JSON registration defaults to a 16 KiB buffer and a maximum depth of 64. Configure `Platform:Serialization:DefaultBufferSizeBytes` between 4 KiB and 1 MiB and `Platform:Serialization:MaxDepth` between 1 and 128. Invalid values fail during registration.