> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secrefs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multiple accounts and vaults

> Two AWS accounts, three Bitwarden projects, one config.

The provider segment of a reference is an **alias**, not a fixed provider type.
`sec://aws/...` works out of the box because `aws` is a default alias — but you
can register whatever names you like.

```ts theme={null}
import { SecRefs, AwsSecretsManagerProvider } from "@secrefs/node";

const secRefs = new SecRefs({
  providers: {
    "aws-prod":    new AwsSecretsManagerProvider({ region: "us-east-1" }),
    "aws-staging": new AwsSecretsManagerProvider({ region: "us-west-2" }),
  },
});
```

```bash .env theme={null}
DB_PASSWORD=sec://aws-prod/db#password
TEST_DB=sec://aws-staging/db#password
```

The same applies to Bitwarden — one provider instance per machine account or
organization, each under its own alias.

## Default aliases

| Alias       | Provider                               |
| ----------- | -------------------------------------- |
| `aws`       | AWS Secrets Manager                    |
| `vault`     | HashiCorp Vault                        |
| `bitwarden` | Bitwarden Secrets Manager              |
| `local`     | Gitignored local JSON, for development |

Passing your own `providers` map replaces these entirely — include any defaults
you still want.

## A note on AWS profiles

Multiple aliases pointing at different AWS accounts each depend on their **own**
credentials being valid. With SSO that means a live session per profile, and
they expire independently. When one lapses, SecRefs names which alias failed:

```
Cannot authenticate to provider "aws-staging".
```

so you know which `aws sso login` to run.

## Using aliases from the CLI

Drop a `secrefs.config.json` at your project root. `secrefs run` finds it from
any subdirectory, the way git does.

```json secrefs.config.json theme={null}
{
  "providers": {
    "aws-prod":    { "type": "aws", "profile": "acme-prod", "region": "us-east-1" },
    "aws-staging": { "type": "aws", "profile": "acme-stg" },
    "bw-eng":      { "type": "bitwarden", "tokenEnv": "BWS_TOKEN_ENG" }
  }
}
```

<Warning>
  **This file never holds a credential, and the parser refuses to let it.**
  Every secret is referenced by the *name* of the environment variable that
  carries it (`tokenEnv`) or by an AWS profile name. A config file that could
  hold a token would recreate the `.env` problem one level up, in the tool built
  to solve it — so `"token"`, `"password"`, `"apiKey"` and similar keys are
  rejected outright rather than ignored.
</Warning>

Declared aliases **replace** the four built-ins rather than merging with them. A
project that declares `aws-prod` and `aws-staging` almost certainly does not
want a third, differently-configured `aws` still quietly resolving — that is how
a reference reaches the wrong account.

The CLI prints which config it loaded, because "which config am I actually
using" is the first question when an alias resolves somewhere unexpected:

```
secrefs: using secrefs.config.json (3 aliases: aws-prod, aws-staging, bw-eng)
secrefs: resolved 2 secret reference(s): DB_PASSWORD, TEST_DB
```

## Service identity lifetime

When an application authenticates to a SecRefs control plane rather than
using ambient credentials, it does so as a **service identity**. Those can be
given a lifetime:

```bash theme={null}
POST /v1/service-identities
{ "orgId": "...", "name": "ci-deploy", "expiresInDays": 90 }
```

Omit `expiresInDays` and the identity never expires — which is the default, and
is what every identity created before this existed still has.

The console shows each identity's expiry alongside **when it was last used**.
The second is usually the more useful of the two: a token rotated on schedule
was never the risk. The one nobody has touched in eight months is.