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

# Connections & secrets

> Custom API nodes reference named connections; connections hold credentials. How they're stored, scoped and rotated.

A **connection** is a named bundle of credentials + base URL + transport config that one or more nodes share. The connection name appears on every node that uses it, never the credentials themselves.

## How a connection is referenced

A `customApi` node carries `connectionName: "..."`. The engine resolves that name against the workflow's `connections` map at runtime — bringing in the right credentials and base configuration without ever embedding them in the workflow definition.

Common connections in production workflows:

| Connection               | Used by                                                   |
| ------------------------ | --------------------------------------------------------- |
| Identity-suite admin API | Sumsub admin overrides, scoped re-verification tokens     |
| Issuer                   | Cardholder provisioning, card-programme lifecycle         |
| Notification callback    | Client-app webhooks (SDK launch, lifecycle updates)       |
| Registry                 | Tax-authority validation (e.g. Receita Federal in Brazil) |
| Payment-rail directory   | PIX DICT lookups                                          |
| Regulator                | COAF / Gov.br submission, future direct-API regulators    |
| Internal case store      | Internal HTTP services Frayme owns                        |

## Storage and scoping

Connections live outside the workflow definition — they're managed at the tenant level so:

* Multiple workflows share the same connection without duplicating credentials.
* Rotation in one place propagates everywhere.
* Audit logs reference the `connection_id` rather than embedding the secret.

In production, connection secrets are stored in a secrets manager (AWS Secrets Manager / Vault). In the demo they live in environment variables resolved at startup.

## Rotation

<Steps>
  <Step title="Open the connection">
    Settings → Connections → click the connection.
  </Step>

  <Step title="Stage new credentials">
    Paste the new key/cert. Old credentials remain active.
  </Step>

  <Step title="Test">
    Run the built-in synthetic round-trip against a known-safe endpoint.
  </Step>

  <Step title="Promote">
    Switch the connection's primary credential to the new one. New calls hit it immediately; in-flight calls drain on the old one.
  </Step>

  <Step title="Revoke">
    After the drain window, revoke the old credential upstream.
  </Step>
</Steps>

## What's available at templating time

When a node executes against a connection, the templating layer can reference the named secrets registered to that connection. The exact list depends on what the connection ships — for an HTTP-based connection it's typically an API token, a signing key, and any provider-specific headers.

The templating layer does **not** expose the connection's base URL or its full credential bag. Custom API nodes still declare their full URL in `endpoint`; the connection's base config (mTLS cert, timeouts, retry policy) is applied transparently.

## Connection vs Data Source

|                               | Connection                                                                           | Data Source                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| **What it holds**             | Credentials + transport config                                                       | Provider profile + health + pricing                                |
| **Referenced by**             | `customApi` nodes (`connectionName`)                                                 | `dataSource` nodes (`providerId`)                                  |
| **Use case**                  | Bespoke HTTP integrations (registries, banking rails, regulators, internal services) | Catalogued vendor calls (Sumsub, LSEG, BigDataCorp, Crystal, etc.) |
| **Frayme-resold credentials** | Sometimes (vendor admin APIs)                                                        | Always (`apiKey: "frayme-resell-managed"`)                         |