Platform

Secrets and credentials

Connectors act on your systems with credentials you grant them, which makes credential handling the most consequential plumbing in the platform. The rules are few and absolute: credentials live in a managed secret store, encrypted at rest and keyed per tenant; they are injected into the connector runtime at call time; and they never appear in a prompt, a plan, a receipt, or a log. This page covers where credentials live, how they are scoped, how rotation works, and how to verify a credential is healthy.

Two kinds of secret

Fibric handles two distinct kinds of secret, and they never mix:

Kind	What it authenticates	Who holds it
API keys (`sk_live_…`)	Your requests to Fibric. A key identifies exactly one tenant and enforces the tenancy wall; nothing in a request body can override it.	You. Shown once at creation, revocable individually, never stored in recoverable form by the platform.
Connector credentials	Fibric's outbound calls to your systems: an OAuth grant to your CRM, an API key for your commerce platform, an IAM role for your telephony stack.	The platform's secret store, on your behalf, keyed to your tenant.

API key handling is covered in the API overview; expired or revoked keys fail with key_invalid or key_revoked (Errors). The rest of this page is about connector credentials.

Where credentials live

Connector credentials are stored in AWS Secrets Manager within Fibric's managed cloud, encrypted at rest, and keyed per tenant per connector installation. This is a runtime commitment written into the connector SDK contract itself: a connector author declares what kind of auth their connector needs, and the runtime, not the author's code, resolves the actual secret:

packages/connector-sdk/src/index.ts

// Authors declare auth + tools + events + probe; the RUNTIME provides
// per-tenant creds (Secrets Manager), rate-limited/retrying HTTP, idempotency, OTel.

export interface ConnectorCtx {
  tenant_id: string;
  reseller_id: string | null;
  config: Record<string, unknown>;
  // in prod: ctx.http is a per-tenant, rate-limited, retrying client w/ creds from Secrets Manager
  log: (msg: string, extra?: Record<string, unknown>) => void;
}

The consequences of this shape:

Connector code never sees raw secrets. The tool handler receives a pre-authenticated HTTP client. There is no ctx.apiKey to read, log, or leak; a connector author cannot mishandle a credential their code never holds.
Scoping is per tenant, structurally. The client is constructed for the tenant_id on the context, resolving that tenant's secret alone. One tenant's key cannot serve another tenant's request, because the resolution path starts from the verified tenant identity, the same identity that scopes row-level security.
config is for configuration, not secrets. Non-secret settings, a store URL, a region, a queue name, travel in config. Secret material is entered once at install and goes only to the secret store.

Auth kinds

A connector declares its auth requirement as an AuthSchema, one of six kinds. The kind determines what you are asked for at install and what rotation looks like.

Kind	You provide at install	Rotation behavior
`oauth2`	An authorization grant, via the provider's consent screen, with the scopes the connector declares.	Access tokens refresh automatically from the refresh token. Rotation means re-consenting; revoking the grant at the provider disables the connector immediately.
`api_key`	A key issued by the source system.	Manual: issue a new key at the source, update the installation, then revoke the old key at the source.
`basic`	A username and password (or app password).	Manual, as for `api_key`.
`aws_iam`	A role ARN Fibric can assume, scoped to the actions the connector's tools require.	No long-lived secret is stored; credentials are short-lived by construction. Rotation means editing the role's trust or permissions policy.
`mtls`	A client certificate and key.	Manual: install the successor certificate before the incumbent expires.
`none`	Nothing. Used by sandbox and public-data connectors.	Not applicable.

Declaring auth in a connector is one line, for example auth: oauth2({ scopes: ["orders.read", "orders.write"] }); see Tools & auth for the authoring view.

Grant the minimum

A connector's tools define exactly what it can be asked to do, and the trust gate constrains that further, but the credential you grant is the outer bound. Issue keys and roles scoped to what the connector's tools actually touch: a connector whose tools only read orders does not need a key that can edit products.

Rotating a credential

Rotation is an update to the connector installation followed by a verification. The sequence that avoids downtime:

bash

# 1. issue the new credential at the source system (old one still valid)

# 2. update the installation with the new credential
fibric connectors add cn-magento --as orders   # re-running install prompts for credentials

# 3. verify the connector against the source with the new credential
fibric connectors test orders

# 4. revoke the old credential at the source system

Updating a credential replaces the secret in place; in-flight tool calls complete on the client they started with, and subsequent calls resolve the new secret. If step 3 fails, the test reports auth_failed (Errors) and the old credential is still live at the source, so you can retry without an outage. The same flow is available in the console and through the Connectors API (POST /v1/connectors/{id}/test).

A credential that expires or is revoked without rotation surfaces as failing tool calls and a failing probe; the symptom-level walkthrough is in Troubleshooting.

Never in prompts, never in logs

The place a credential could do the most damage is inside a model context, where a prompt injection could exfiltrate it, or inside a log, where retention outlives intent. Fibric's protection is structural rather than filter-based: the credential is simply absent from every one of those surfaces.

Surface	Why credentials cannot appear there
Operator context (prompts)	Operators receive envelopes and capability results, and emit plans. The credential is resolved inside the connector runtime, on the far side of the deterministic executor, after the reasoning step has already finished. There is no path by which secret material enters the model's input.
Plans and actions	A `PlannedAction` names a capability and a tool with arguments. Authentication is not an argument; the runtime supplies it.
Receipts	Receipts record dispositions and results. API keys and connector credentials are never written into a receipt, so exporting your ledger never exports a secret.
Platform logs	Connector code logs through `ctx.log`, and has no credential in scope to log. Platform request logs record key identity, never key material.

Do not put secrets in payloads

The platform keeps its surfaces clean, but an event payload is your content, and it flows to operators and into the event log. Never place credentials, tokens, or personal secrets in event payloads or tool args. If a source system's webhook includes a secret field, strip it in the connector's event mapping before the envelope is created.

Verifying credential health

Every connector may declare a probe, a cheap authenticated call that proves the credential works and returns a status with an optional headline metric. Probes back the connector status you see in the console and the CLI:

bash

$ fibric connectors list
ROLE     CONNECTOR    STATUS   NOTE
orders   cn-magento   ready    probe ok
crm      cn-kustomer  error    auth_failed: token rejected by source

Treat a failing probe as an expired or revoked credential until proven otherwise, and follow the rotation sequence above. Continue with the security model for where secrets fit in the wider enforcement picture, and Environments for keeping sandbox and production credentials apart.

Secrets and credentials

#Two kinds of secret

#Where credentials live

#Auth kinds

#Rotating a credential

#Never in prompts, never in logs

#Verifying credential health