Connector auth patterns

Auth in the Connector SDK is a declaration, never an implementation. The manifest states the kind of credential a connector needs; the platform acquires it per tenant, stores it in the tenant's secret store, refreshes and rotates it, and injects it into ctx.http at call time. Your handler never sees a token. This page covers each pattern in working depth: API keys, both halves of OAuth 2.0, AWS IAM with cross-account roles, rotation, and where the material actually lives.

#The declaration model

The whole auth surface of the SDK is one type and three helpers:

export type AuthKind = 'oauth2' | 'api_key' | 'basic' | 'aws_iam' | 'mtls' | 'none';

export interface AuthSchema {
  kind: AuthKind;
  scopes?: string[];        // meaningful for oauth2 only
}

export function oauth2(opts: { scopes?: string[] } = {}): AuthSchema;
export function apiKey(): AuthSchema;
export function none(): AuthSchema;

Kinds without a helper (basic, aws_iam, mtls) are declared as literals: auth: { kind: 'aws_iam' }. The shape is the API. What the declaration buys you is the split that makes connectors reviewable: everything in this table is the platform's job, and none of it appears in your code.

#API key

The common SaaS case: one long-lived key per vendor account. Declare it with the helper; at connection time the person connecting pastes the key once into the workspace UI or the CLI, and it lands directly in the secret store. Your handler makes plain calls on ctx.http and the runtime attaches the key in whatever form the connector's HTTP profile specifies, header or query, without the handler naming it.

import { defineConnector, tool, apiKey } from '@fibric/connector-sdk';

export default defineConnector({
  id: 'cn-brightdesk',
  version: '1.0.0',
  category: 'comms',
  auth: apiKey(),

  tools: {
    'conversation.read': tool({
      handler: async (ctx, args) => {
        // ctx.http is pre-authenticated; no key appears in connector code
        // return await ctx.http.get(`/v1/conversations/${args.conversation_id}`);
        return { id: args.conversation_id };
      },
    }),
  },
});

$ fibric connectors add cn-brightdesk --connection brightdesk-live
  auth: api_key
  paste the Brightdesk API key (input hidden):
  stored in tenant secret store as connections/brightdesk-live
  probe: ok  (open conversations: 214)

Prefer a key minted for Fibric specifically, scoped as narrowly as the vendor allows, over a shared admin key. When the vendor supports multiple keys, rotation becomes a zero-downtime operation; see rotation.

#OAuth 2.0

Declare oauth2() with exactly the scopes your tools need. Review compares declared scopes against your tool surface, and a def asking for write scopes with no side-effecting tool fails review.

auth: oauth2({ scopes: ['conversations.read', 'notes.write'] }),

#Authorization code flow

Connecting an oauth2 connector runs the standard authorization code grant, driven entirely by the platform:

1. The person connecting clicks through to the vendor's consent screen, carrying your declared scopes and a state parameter bound to the connection.
2. The vendor redirects back to the platform's callback with the authorization code. Connector code hosts no callback and sees no code.
3. The platform exchanges the code for an access token and, where offered, a refresh token, and writes both to the tenant secret store under the connection.
4. The probe runs once to confirm the grant actually works before the connection is marked healthy.

Client credentials for the OAuth app itself (client id and secret) are registered once per connector at publish time, not per tenant, and are held platform-side. A tenant connecting your listing never handles them.

#Refresh and expiry

The runtime refreshes proactively: when a call is about to go out on ctx.http and the access token is inside its expiry window, the refresh happens first, under a per-connection lock so concurrent tool calls never race two refreshes against a vendor that rotates refresh tokens on use. Handlers observe none of this. Two failure modes surface to operators of the tenant rather than to your code:

#AWS IAM and cross-account roles

For AWS-native targets, declare { kind: 'aws_iam' }. No long-lived secret exists under this kind at all: the connection stores a role ARN and an external id, and the runtime obtains short-lived credentials by assuming the role at call time. This is the pattern the live cn-amazon-connect connector uses.

Connecting is a cross-account handshake:

1. The platform shows the tenant the exact trust policy to create: a role in the tenant's AWS account trusting Fibric's connector principal, conditioned on a connection-specific external id.
2. The tenant creates the role, attaches a permissions policy scoped to what the connector's tools need, and pastes the role ARN back.
3. The platform performs a test sts:AssumeRole with the external id and runs the probe. Only then is the connection healthy.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "connect:GetContactAttributes",
      "connect:ListContactFlows"
    ],
    "Resource": "arn:aws:connect:us-east-1:111111111111:instance/EXAMPLE/*"
  }]
}

#Token and key rotation

Rotation is a platform operation on the connection, never connector code. What rotation means differs by kind:

$ fibric connectors rotate cn-brightdesk --connection brightdesk-live
  paste the replacement credential (input hidden):
  probe with staged credential: ok
  committed. previous credential released; revoke it at the vendor now.

Every rotation is itself recorded: connection credential changes appear in the tenant's audit stream with who, when, and which connection, though never the material.

#Storing secrets

All credential material lives in the tenant's secret store, keyed by connection, encrypted at rest, and readable only by the connector runtime executing under that tenant. The rules for connector authors are absolute, and marketplace review enforces them:

• Never accept a credential through config. The config record on ConnectorCtx is for non-secret settings: subdomains, regions, queue names. It is visible in the workspace UI.
• Never log material. ctx.log output lands in traces and receipts people read. Log identifiers, not tokens.
• Never persist a credential in connector state, cache it in module scope, or write it to disk. If a token needs refreshing, that is the platform's job.
• Never forward a credential to a third system. A connector authenticates to its one target; fan-out is an architecture smell and a review failure.

The full secret-store reference, including bring-your-own-KMS-key and access audit, is on secrets.

#Choosing a pattern

#Keep going

• Secrets: the tenant secret store in full.
• Tools & auth: the declaration surface next to the tool contract.
• Connector manifest: where auth sits in the def.
• Tenancy & isolation: why a connection's credentials can only ever serve one tenant.