Multiple accounts and vaults

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.

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" }),
  },
});

.env

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.

secrefs.config.json

{
  "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" }
  }
}

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.

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:

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.

Getting started

Providers

Guides

Reference

Multiple accounts and vaults

Default aliases

A note on AWS profiles

Using aliases from the CLI

Service identity lifetime

​Default aliases

​A note on AWS profiles

​Using aliases from the CLI

​Service identity lifetime

Default aliases

A note on AWS profiles

Using aliases from the CLI

Service identity lifetime