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, 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:

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