---
title: "Secrets"
slug: "secrets"
description: "Learn how to securely manage sensitive values like API keys and tokens in your connector configuration using the Secrets component for enhanced security."
updated: 2026-06-08T08:35:44Z
published: 2026-06-08T08:35:44Z
canonical: "docs.supermetrics.com/secrets"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

The Secrets component is a connector-level mechanism for declaring sensitive values — such as API keys, access tokens, client secrets, or PII — once and referencing them from authorized parts of the configuration. Each secret is classified by sensitivity and bound to a source that controls how the value is resolved at runtime.

Defining a value as a secret keeps it out of plain-text configuration, allows sensitive values to be stored encrypted, and restricts where the value can appear in the connector configuration. Secrets can also be used for non-sensitive but reusable values (e.g., region codes or tenant IDs) to avoid duplicating literals across many requests.

> **Note:** If you build your connector through the [Connector Builder Hub UI](https://hub.supermetrics.com/connector-builder), the `secrets` object is generated and updated for you automatically when you add or remove secrets in the UI. You only need to author this section by hand when editing the connector JSON directly.

## Registering secrets

Secrets are defined at the connector root level under the `secrets` property. Each entry in `items` is a single secret with a unique `id`, a `classification`, and either a `source` (for built-in resolvers) or a `component` (for custom resolvers).

Below you can find a template for registering secrets:

```
{
  "secrets": {
    "items": [
      {
        "id": "[unique_secret_id]",
        "classification": "[public, secret, or pii]",
        "source": "[userInput, encrypted, or static]",
        "value": "[input field ID, encrypted blob, or static value]"
      }
    ]
  }
}
```

The most common values for `source` are:

| Source | Description |
| --- | --- |
| `userInput` | The secret is collected from the user during the authentication flow. `value` is the ID of the user input field that holds it. |
| `encrypted` | The secret is baked into the connector as an encrypted blob. `value` is the encrypted string. |
| `static` | The secret is a plain-text constant. Only allowed for `public` and `pii` classifications — never for `secret`. |

Adding a secret to the `items` list alone does not inject the value anywhere. Each consumer must explicitly reference the secret by its `id`, in one of two ways:

1. **As a placeholder** — using `{{ secrets.<id> }}` inside any field where secret placeholders are permitted (e.g., request URLs, headers, parameters, and body content).
2. **As a `ValueSourceObject`** — with `source: "secret"` and `value: "<id>"`, in any field that supports the `secret` source (currently the signer algorithm key in [Request signers](https://docs.supermetrics.com/docs/request-signers), with adoption in other components expected over time).

Below you can find an example of consuming a registered secret as a placeholder in a request header:

```
{
  "url": "https://api.example.com/data",
  "headers": [
    { "key": "X-API-Key", "value": "{{ secrets.api_key }}" }
  ]
}
```

## Secret resolved by a component

In addition to the built-in `source` types, a secret can be resolved by a custom component. Instead of providing a `source`, you provide a `component` that identifies which resolver should look up the value at runtime. This is useful when the value lives outside the connector configuration — for example, in the Connector Builder vault.

> **Note:** The `connector_builder_vault` component refers to the same vault that the Supermetrics Hub UI uses to store secrets. Any secret you add through the UI is written to this vault and can be referenced from the connector configuration using the pattern shown above.

Below you can find an example of a secret resolved by the Connector Builder vault component:

```
{
  "secrets": {
    "items": [
      {
        "id": "managed_token",
        "classification": "secret",
        "component": {
          "override": {
            "componentId": "connector_builder_vault"
          }
        },
        "value": "secrets_api_token"
      }
    ]
  }
}
```

In this example:

1. At runtime, the system uses the component identified by `componentId` (here, `connector_builder_vault`) to resolve the secret.
2. The component receives `value` (`secrets_api_token`) as the lookup identifier.
3. The resolved value becomes available via `{{ secrets.managed_token }}` in any allowed location, exactly the same way as a secret resolved through a built-in source.

> **Note:** A secret entry must specify either a `source` or a `component`, but not both. Use `component` only when none of the built-in sources fit your case.