Share secrets
Learn how to securely use credentials in listeners.
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.
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.
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.