> 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/engineering-and-delivery/security-and-operations.md).

# Security and operations

PAL.NET is intended for high-assurance integrations. Treat the SDK as a protocol boundary that must preserve the upstream identity, permissions, scopes, and deployment controls.

## Secret handling

Never log or expose:

* bearer tokens and client secrets;
* authorization or proxy-authorization headers;
* licence file contents or private keys;
* raw token endpoint responses;
* unredacted upstream error parameter values;
* full payloads unless a controlled diagnostic policy explicitly allows them.

{% hint style="warning" %}
Payload diagnostics are disabled by default. If explicitly enabled for a short-lived diagnostic session, apply host redaction, access controls, retention limits, and customer approval.
{% endhint %}

## Structured diagnostics

PAL.NET emits operation-aware diagnostics through standard logging and activity abstractions. Useful fields include operation ID, status, attempt count, retry exhaustion, classification, and upstream diagnostic ID. Diagnostic IDs are safe correlation values; they are not credentials.

Use the upstream diagnostic ID when contacting platform support. Do not attach the complete request or response body by default.

## Timeouts and cancellation

Set `RequestTimeout` to match the host's service-level objective and upstream operation characteristics. Always pass a caller cancellation token:

```csharp
await client.GetAsync(datasetRid, httpContext.RequestAborted);
```

Cancellation stops token acquisition, backoff delays, request execution, response reads, page enumeration, polling, and stream consumption where the underlying operation supports it.

## Retry and mutation safety

Retries are safe only when the request and body can be replayed without duplicating a side effect. Keep mutations non-idempotent unless the upstream contract provides an idempotency key or equivalent guarantee. Observe `Retry-After` and use bounded budgets.

{% hint style="warning" %}
Do not add a second generic retry policy around PAL.NET without considering duplicate mutation risk. If the host retries a whole message or HTTP request, make that business operation idempotent independently of the SDK transport retry.
{% endhint %}

## Resource ownership

Dispose:

* `PalantirStreamingResponse`;
* `PalDatasetTable`;
* `PalSqlQueryResult`;
* request body streams transferred to PAL.NET;
* DI scopes containing streamed operations.

{% hint style="warning" %}
Unclosed response streams can hold sockets and diagnostic scopes open, eventually exhausting the connection pool.
{% endhint %}

## Deployment profiles

For online deployments, use approved secret-backed token and licence providers. For restricted/offline environments, use the signed offline entitlement path and approved proxy/certificate configuration. Validate the full profile before release acceptance, including clock synchronization, file permissions, key rotation, and package provenance.