declaring secrets (app.Secrets)

Summary#

app.Secrets declares the named secrets your application consumes — a provider's API key, an access token, an OAuth client secret. You declare a secret's name here; you never write its value in source.

⚠ Not the API key of an API your app PUBLISHES. That is a different direction and a different mechanism: a published app.Apis route gated Auth = new ApiAuth { ApiKey = true } is authenticated by a per-user key kept on the app's [Principal] row, and nothing in ApiAuth names a Secret. See publishing a REST API (app.Apis).

Each secret is new Secret("Name"), and optionally { UserScoped = true } to make it a per-user secret rather than a single app-wide value. Every other config slot that needs a secret refers to it by its Secret.Name handle rather than by an inline string.

app.Secrets = [
  new Secret("OpenAI"),
  new Secret("PersonalToken") { UserScoped = true },
];

Signature#

app.Secrets = [                              // one entry per named secret
  new Secret("Anthropic"),                            // app-wide: one value for the whole app
  new Secret("CalendarToken") { UserScoped = true },  // per-user: each user supplies their own value
];

app.Secrets is a list — an app may declare as many named secrets as it needs. Everywhere else refers to one by its Secret.Name handle and never by a literal: on a model client, on the embedder's ApiKey, on an OAuth client's ClientSecret, in a function body. The worked form is under Examples below.

Description#

Declaring one is what brings the storage in. app.Secrets = [ … ] is a declaration trigger: writing it opts the app into the Osysharp.Secrets capability, which is where the values are kept. There is no use line to write and never was — the declaration IS the request, so an app that declares no secret carries no secret table at all. (Before 2026-09 every app carried it regardless; of 53 projects measured, 7 declared a secret and 46 did not.)

Each entry is a new Secret("Name"), where the name is a string literal. That name is the only thing that lives in source. The secret's actual value — the key, token, or password — is never written in your app; it lives in the secret store and is supplied separately. On your own machine you supply it with osy secret set (Giving a secret its value); a deployed app's values are supplied by whoever operates its platform.

• new Secret("Name") — declares an app-wide secret. There is one value, shared by the whole application, used for every request regardless of who makes it (for example, one server-side API key for a provider).
• { UserScoped = true } — makes the secret per-user instead. Every user of the app supplies their own value, and the secret resolves to the value belonging to the current user. Use this when the credential belongs to the person, not the app (for example, a user's personal access token).

Once declared, a secret is referenced everywhere else by its Secret.Name handle — not by re-typing the name as a string and never by the value. A model client's ApiKey, an OAuth client's ClientSecret, and a REST API's key all take a Secret.Name handle. The handle is how the platform links a config slot to the stored value at runtime while keeping the value itself out of your source.

Examples#

Declare an app-wide secret and reference it from the embedder's ApiKey:

app.Secrets = [ new Secret("OpenAI") ];

// The handle is read where the thing that needs it is declared; the value never appears in source.
app.Embedding = new EmbeddingConfig {
  Provider   = EmbeddingProvider.OpenAI,
  Model      = "text-embedding-3-small",
  ApiKey     = Secret.OpenAI,
  Dimensions = 1536,
};

A per-user secret — each user supplies their own value:

app.Secrets = [ new Secret("PersonalToken") { UserScoped = true } ];

See also#

• reading a secret's value (Secret.Name) — reading a declared secret's VALUE inside a function body
• Giving a secret its value — how a declared secret gets its value on your machine
• OAuth clients (app.OAuthClients) — an OAuth client's ClientSecret is a Secret.Name handle
• embedding provider (app.Embedding) — app.Embedding, whose ApiKey is a Secret.Name handle
• The Llm kit — call a model, and know what each call cost — a model's client takes one the same way: new AnthropicClient { ApiKey = Secret.Anthropic }
• publishing a REST API (app.Apis) — app.Apis. ⚠ A REST API's key is NOT one of these: ApiAuth names no Secret, and a published API's key is a per-user credential kept on the [Principal] row