---
title: Retrieve a secure configuration setting
summary: Read a secure setting by track using a caller-supplied system hash.
status: draft
owner: SAIF Framework
last_reviewed: 2026-07-30
library: SAIF.Framework.Security.EnvironmentApi
reference_type: package
operation_id: OP-ENV-005
trigger: Caller invokes GetSecureConfigSetting or GetSecureConfigSetting<T>
---

# Retrieve a secure configuration setting

This operation calls the Environment API's secure-setting route, which returns values that are gated by track and by a system hash rather than served from the general-purpose cache. It resolves the current track, shapes the request URL to match whether the caller's key is section-qualified, and returns either the raw string or a converted value.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-ENV-005 |
| **Trigger** | Caller request to read a secure configuration value |
| **Inputs** | `configKey`, `systemHashValue` |
| **Outputs** | Secure setting value as `string` or converted `T` |
| **Primary components** | `EnvironmentServiceBase.GetSecureConfigSetting`, `EnvironmentServiceBase.GetSecureConfigSetting<T>` |
| **Entry point** | `SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs` |

## Steps

1. Resolve the current application track through `GetApplicationTrack()`, which loads configuration first when the shared cache is still empty.
2. Start the request path at `{EnvironmentApiUrl}/v2/` and branch on whether `configKey` contains a section delimiter (`.`) ([BR-002](../business-rules.md#br-002-environment-api-base-url-must-be-present)).
3. If the key is section-qualified, split it into `section` and `key` and build `/secureSetting/{ApplicationId}/{track}/{section}/{key}/value?systemHashValue=...`.
   - Otherwise build the simpler `/secureSetting/{ApplicationId}/{track}/{configKey}/value?systemHashValue=...` route.
4. Download the JSON response and deserialize it directly to a `string`.
5. Return the raw string result, or convert it to `T` through `Convert.ChangeType` when the caller used the generic overload.
6. Let any HTTP or serialization failure surface to the caller rather than masking it.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller requests secure setting]) --> Track[Resolve application track]
	Track --> Split{Key includes section?}
	Split -->|Yes| SectionUrl[Build section-qualified secure-setting URL]
	Split -->|No| DirectUrl[Build direct secure-setting URL]
	SectionUrl --> Download[Download JSON payload]
	DirectUrl --> Download
	Download --> Deserialize[Deserialize string value]
	Deserialize --> End([Return string or converted T])
```

## Failure and edge-case behavior

- The method trusts the caller-supplied `systemHashValue` as-is; it does not validate hash age locally, so lifetime enforcement must happen through a separate call to [Validate system hash lifetime](validate-system-hash-lifetime.md) or on the server side.
- Section-qualified and global keys resolve to different route shapes, so a caller must format `configKey` consistently with how the setting was stored.
- The generic overload performs only a direct `Convert.ChangeType` conversion, so it will fail for types that conversion cannot bridge.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Configuration](../configuration.md)

## Sources
- SAIF.Framework.Security.EnvironmentApi\Services.Common\EnvironmentServiceBase.cs