# declaring secrets (app.Secrets)

> `app.Secrets` declares the named secrets your app uses — API keys, tokens, client secrets. Each is `new Secret("Name")`, optionally `{ UserScoped = true }` for a per-user secret rather than one app-wide value. Everything else references a secret by its `Secret.Name` handle — `app.DefaultModel`'s `ApiKey`, an OAuth client's `ClientSecret`. A secret's VALUE is never in source, only its name; the value lives in the secret store.

<!-- id: config-secrets · area: config · stability: stable · html: https://osysharp.com/reference/config/secrets/ -->

## Summary        {#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)](https://osysharp.com/reference/api/rest/).

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.

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

## Signature      {#signature}
```osy
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    {#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](https://osysharp.com/reference/local/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       {#examples}
Declare an app-wide secret and reference it from the default model's `ApiKey`:

```osy title="basic" test app=config-secrets-example
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:

```osy title="user-scoped" test app=config-secrets-userscoped
app.Secrets = [ new Secret("PersonalToken") { UserScoped = true } ];
```

## See also       {#see-also}
- [reading a secret's value (Secret.Name)](https://osysharp.com/reference/function/secret-read/) — reading a declared secret's VALUE inside a function body
- [Giving a secret its value](https://osysharp.com/reference/local/giving-a-secret-its-value/) — how a declared secret gets its value on your machine
- [OAuth clients (app.OAuthClients)](https://osysharp.com/reference/config/oauth-clients/) — an OAuth client's `ClientSecret` is a `Secret.Name` handle
- [default LLM model (app.DefaultModel)](https://osysharp.com/reference/agent/default-model/) — `app.DefaultModel`, whose `ApiKey` references a declared secret
- [publishing a REST API (app.Apis)](https://osysharp.com/reference/api/rest/) — `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