The .NET client

Code can read a vault directly with the .NET client instead of receiving values at start-up. The client reads secrets; it does not create, change or delete them — use the portal, the CLI or the API for that.

Add the packages

• Stackship.Secrets.Client — the client. It targets .NET Standard 2.1, .NET 8 and .NET 10.
• Stackship.Identity.Client — the credentials the client signs in with. The credential support in the Secrets client is available on .NET 10.

Read a secret

Use the vault service's address, https://secrets.apps.example.com, and the vault's name:

using Stackship.Identity.Client;
using Stackship.Secrets.Client;

var client = new SecretClient(
    "https://secrets.apps.example.com",
    "my-vault",
    new DefaultStackshipCredential());

var secret = await client.GetSecretAsync("api-key");      // null when there is no such secret
var older  = await client.GetSecretVersionAsync("api-key", 2);

A SecretValue carries Name, Value, Version, ContentType and CreatedAt. Values are cached in the process for 300 seconds by default (the last constructor argument).

How the client signs in

DefaultStackshipCredential picks the first credential its environment provides:

1. a managed identity, when STACKSHIP_IDENTITY_RESOURCE_UID and STACKSHIP_IDENTITY_TOKEN_ENDPOINT are set — the platform sets them in app and function containers;
2. a service account, from STACKSHIP_CLIENT_ID, STACKSHIP_CLIENT_SECRET and STACKSHIP_TOKEN_ENDPOINT (optionally STACKSHIP_AUDIENCE).

Whichever it is needs Secrets Reader on the vault — see Give a workload access.

Load secrets into configuration

AddStackshipSecrets adds named secrets to .NET configuration at start-up. A -- in a secret's name becomes : in the configuration key, so the secret ConnectionStrings--Default is read as Configuration["ConnectionStrings:Default"].

It does not use DefaultStackshipCredential: give it a token yourself, through TokenProvider (or a fixed BearerToken):

var credential = new DefaultStackshipCredential();

builder.Configuration.AddStackshipSecrets(options =>
{
    options.BaseUrl = "https://secrets.apps.example.com";
    options.VaultName = "my-vault";
    options.TokenProvider = async ct => (await credential.GetTokenAsync(ct)).Token;
}, "ConnectionStrings--Default", "ApiKeys--Stripe");

Important

A secret that cannot be read — no token, no access, no such secret — is skipped without an error, so a missing token leaves the configuration silently empty. Check for missing keys yourself.

With ReloadOnInterval = true the secrets are loaded again every ReloadIntervalSeconds (300 by default). Each load replaces the previous values, so a secret that fails to load on a reload is missing from configuration until a later load succeeds.