With Secrets you can securely share credentials with listener implementations without developers explicitly knowing the secret values upfront. Secret values are set in the user interface, but retrieved via the SDK or API.

​
Overview

​
Creating Secrets

Secrets in Flatfile, defined as Name/Value pairs, are securely stored and associated with an Environment or a Space. Spaces will inherit Secrets from their respective Environment but you may choose to override any Environment Secret for a given Space. To define Secrets shared with every Space in an Environment, navigate to the “Developer Settings” screen for that environment. To override an Environment value, navigate to the specific Space and select “Secrets” in the left navigation.

While Flatfile encrypts all data, both during transit and at rest in our datastore, Secrets have an additional layer of protection. Secrets are encrypted/decrypted on demand using a unique set of keys. As such, a potential intruder would need not only access to the plaintext datastore, but also these extra keys to decrypt and compromise these sensitive values.

​
Consuming Secrets

While Secrets are defined in administrative interfaces for Environments and Spaces, respectively, they are designed to be consumed by Listeners. While it might be trivial to pass in secret values through environment variables in a self-hosted Listener, with a Flatfile hosted Agent based Listener one must use the Secrets features. See Usage below for some example consumer patterns.

​
Usage Examples

​
Sensitive Credentials

The principal utility of Secrets lies in securely storing sensitive credentials/tokens within an Environment/Space for connecting Listeners to third-party APIs. For instance, you might store a secret named SLACK_TOKEN with a value, allowing you to communicate with a Slack bot each time a custom action is triggered.

For complete examples of secure credential management, see the Authentication Examples guide.

​
Example Listener

In this example, we use an event.secrets call to pull a sensitive Slack token for use within a listener context. We then can use the credential to post a message to Slack.

export default function flatfileEventListener(listener) {
  //note: listening to all events with a wildcard can be used while testing but is not
  //recommended for production, as it will capture all events and may cause performance issues
  listener.on("**", async (event) => {
    const tok = await event.secrets("SLACK_TOKEN");
    console.log(tok);
    /* pseudo code for an example
    slack = new Slack(tok);
    slack.api(
      "chat.postMessage",
      {
        text: "Flatfile event received!",
        channel: "#integration-flatfile",
      },
      function (err, response) {
        console.log(response || err);
      }
    ); */
  });
}

​
Example Listener using optional props

The options parameter for the secrets fetch function allows optionally choosing a different Environment or Space than the event occurred within.

export default function flatfileEventListener(listener) {
  //note: listening to all events with a wildcard can be used while testing but is not
  //recommended for production, as it will capture all events and may cause performance issues
  listener.on("**", async (event) => {
    // Hardcode specific environment and space for this listener's case
    const credential = await event.secrets("MY_CREDENTIAL", {
      environmentId: "us_env_123",
      spaceId: "us_spa_123",
    });
    console.log(credential);
  });
}

​
Metadata

While it might seem creative to use the Secrets feature to hold non-sensitive metadata, we encourage you to learn more about utilizing metadata within your Spaces, Records, or Fields.