> ## Documentation Index
> Fetch the complete documentation index at: https://flatfileinc-remove-rss-json.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Share secrets

> securely use credentials in listeners

<Snippet file="shared/dxpbanner.mdx" />

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](https://reference.flatfile.com/api-reference/secrets/list-secrets).

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

<Note>
  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.
</Note>

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

<Snippet file="guides/secrets/block1.mdx" />

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

<Snippet file="guides/secrets/block2.mdx" />

## 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](./metadata)
within your Spaces, Records, or Fields.

## Example Project

Find the secrets example in the Flatfile GitHub repository.

<CardGroup cols={2}>
  <Card title="typescript" icon="code-merge" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/typescript/secrets/index.ts">
    Clone the secrets example in Typescript
  </Card>

  <Card title="javascript" icon="js" href="https://github.com/FlatFilers/flatfile-docs-kitchen-sink/blob/main/javascript/secrets/index.js">
    Clone the secrets example in Javascript
  </Card>
</CardGroup>