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
];

// referenced elsewhere by handle, never by literal value:
app.DefaultModel = new LlmConfig { ApiKey = Secret.Anthropic };

app.Secrets is a list — an app may declare as many named secrets as it needs.

Description#

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. app.DefaultModel'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 default model's ApiKey:

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

app.DefaultModel = new LlmConfig {
  Provider = LlmProvider.OpenAI,
  Model    = "gpt-4o",
  ApiKey   = Secret.OpenAI,
};

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
• default LLM model (app.DefaultModel) — app.DefaultModel, whose ApiKey references a declared secret
• 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