The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!
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 of xoxb-e5b7206ccac446048a8a52b703dbb4b9, allowing you to communicate with a Slack bot each time a custom action is triggered.

​
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) {
  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);
      }
    ); */
  });
}
// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/secrets/index.js)
See full code example in our flatfile-docs-kitchen-sink Github repo

​
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) {
  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);
  });
}
// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/secrets/index.js)
See full code example in our flatfile-docs-kitchen-sink Github repo

​
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.

​
Example Project

Find the secrets example in the Flatfile GitHub repository.

typescript

Clone the secrets example in Typescript

javascript

Clone the secrets example in Javascript