Secrets

Nitric Secrets makes securely storing, updating and retrieving sensitive values like database credentials and API keys easy.

Secrets

Secrets are values stored in an encrypted Secrets Manager, usually containing sensitive data such as the username and password used to access a database. Since credentials and keys tend to change over time, Nitric Secrets act as a virtual storage location for these values with version control baked in.

Versions

Each secret will contain at least a "latest" version, along with any historical versions of that secret's value. This ensures values, such as encryption keys, can be rotated without losing access to the key used with previously encrypted data.

Values

Values are the secret data attached to a specific secret version, such as the current encryption key or database credentials.

The relationship between Secrets, Versions and Values

The schema below illustrates the relationship between secrets, versions and values for a secret named db.password with two versions:

+- Secret [ 'db.password' ]
|
+- SecretVersion [ '7F5F86D0-D97F-487F-A5A0-11BAAD00F777' ]
| |
| +- SecretValue [ 'bleak_dearest_hanged_reigns' ]
|
+- SecretVersion [ '0581BBD9-C67F-4E8F-849D-38E52CAEE0EB' ]
|
+- SecretValue [ 'crummy_goofed_caddy_radiant' ]

Version IDs are for illustration only. The specific id/numbering strategy depends on the underlying secrets manager of the cloud provider.

The basics

This guide introduces the features of Nitric Secrets.

Create a secret

Creating a new secret can be done in a single line, when a new secret is created a new version is automatically generated.

import { secrets } from '@nitric/sdk';
// Create a new secret
const apiKey = await secrets()
.secret('api-key')
.put('6e1d9008-f06b-1111-2222-9b6989d58999');
// We can get the version ID of our newly created secret using version
apiKey.version;

Secret versioning is automatic. Every time you put a new secret value a new version will be created and set as the latest version.

Access a secret

Accessing the contents of a secret version can be done my calling the access() method.

// access the latest version of a secret
const latestSecret = await secrets().secret('my-secret').latest().access();
// access a known version of a secret
const theSecret = await secrets()
.secret('api-key')
.version('version-id')
.access();

What's next?