The Secrets module enables the use of secrets in flows. A secret is an object with encrypted property values. It can be created, edited and deleted in Cuesta or via the Secrets module.

Reveal a secret

A secret may be encrypted using one of 4 encryption mechanisms:

1. Using a globally shared key built into Manatee and Kwanza. All Manatee instances can encrypt and decrypt these secrets.
2. Using machine-only encryption. The same machine that did the encrypting is the only one that can decrypt again.
3. Using user-only encryption. Only the user that encrypted the secret may decrypt it again.
4. Using a password. The same password must be used to encrypt and decrypt the secret. It is up to you to distribute the password.

Once a secret is saved it is automatically encrypted using one of the schemes above. In Manatee you can then use (and decrypt) the secret:

// "mySecret" is the name or id of the secret
var s = Secrets.reveal("mySecret");
// if a password is stored in the secret we can now use it
new Field("**/password-input-field").input(s.password);

If you have used password-based encryption for your secret you need to supply the password in order to use it:

var s = Secrets.reveal("mySecret", "flsKg023j4e.a10?9");

Secrets saved on the global scope

Secrets left in the global scope after a flow has run are automatically cleared, i.e. they are not available to the next flow on the same application unless revealed again there.

Who can use a secret

A flow can use a secret, i.e. reveal it, update it with keep, or forget it, when at least one of these is true:

• The secret is in Groups that match the Manatee running the flow. They are matched the same way as a flow’s groups: the secret must be in the primary (production) group and in at least one of the secondary groups.
• The running flow is one of the secret’s allowed flows.

If none of the above is true, the call fails with an error saying that the secret is not available.

Creating or updating a secret

You can update the content of an existing secret using the keep method.

Secrets.keep("mySecret", {
  username: "some-user-name",
  password: "pas5w0rd",
  someOtherSecretProperty: "hello",
});

If no secret called “mySecret” exists it will be created as a “global” secret. You can also update/create “machine”, “user” and “shared secret” encrypted secrets.

// For the user that runs this flow
Secrets.keep("only-for-me", { ... }, { type: Secrets.User });
// For all users on the machine that runs this flow
Secrets.keep("only-for-this-machine", { ... }, { type: Secrets.Machine });
// For those who know the "key"
Secrets.keep("only-those-in-the-know", { ... }, { type: Secrets.SharedSecret, key: "aVerySecretPas5w0rd" });

A secret created with keep is not in any groups, so no flow can use it until you add it to groups in Cuesta or create it with onlyInFlows.

A machine or user secret created with keep cannot be updated with keep, but can still be revealed.

Overwrite

When you update an existing secret, the new values are merged with the existing ones by default. If the secret uses a password, use the same password, otherwise the old values stay encrypted with the old password and the new values with the new one. To replace the contents completely, use the overwrite: true option:

// Replace the contents of "mySecret"
Secrets.keep("mySecret", { ... }, { overwrite: true });

Valid until

It is possible to indicate a time when the secret is no longer considered valid. It is not possible to use the secret after this time has passed.

Secrets.keep("mySecret", { ... }, { validUntil: new Date('December 17, 2025 03:24:00') });

Allow specific flows

The onlyInFlows option lists flows that may use the secret even where its groups do not match. It does not stop other flows from using the secret where its groups do match.

Secrets.keep("mySecret", { ... }, { onlyInFlows: ["<flow-identifier>", "<another-flow-identifier>"] });

Passing onlyInFlows when updating a secret replaces its list of flows.

Updating an existing secret

A secret’s type cannot be changed after it has been created, and passing a different type to keep fails. As type defaults to global, leaving it out fails too when you update a secret of any other type. Always pass the secret’s type when updating it.

Delete a secret

To delete a secret you use the forget method:

Secrets.forget("mySecret");