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! 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) {
//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);
}
); */
});
}
// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/secrets/index.js)
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);
});
}
// See full code example (https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/secrets/index.js)
Example Project
Find the secrets example in the Flatfile GitHub repository.
