Connectors: auth, secrets & private networks

A connector is a downstream target agents act on through Provenant. Its credential is held server-side.

The fastest start is a starter pack (Connectors → Start from a pack): a pre-scoped connector for a known vendor plus recommended governance policies — you only add the credential.

Connector scope (optional)

A connector's Allowed actions and Allowed resources are an optional channel-side clamp: they bound what any agent can ever do through this connector, on top of each agent's mandate, policies, and budgets — which always apply (see the intersection model). Blank = any: leave them empty and the mandate/policies/budgets remain the only gates. A call outside the scope is denied with a Connector scope check, named as such in the decision trail and the Activity list.

Authentication schemes

Scheme	Use for
None	simulated connectors, targets that need no credential, and broker-only connectors (see below)
API key	header or query key (`x-api-key`, `?key=`)
Bearer token	static bearer (OpenAI, Stripe, …)
HTTP Basic	username / password
Custom headers	an arbitrary header set
OAuth2 — client credentials	machine-to-machine; Provenant mints + caches access tokens
OAuth2 — refresh token	run the interactive flow once, then reuse the refresh token
AWS SigV4	AWS APIs (per-request signing)
Mutual TLS	APIs that require a client certificate

Secret references

Any secret field accepts a literal or a reference, resolved at call time so the raw secret can stay in your secrets manager. Stored literals are encrypted at rest (AES-256-GCM, per-organization key) and never returned by the API.

Reference	Resolves from
`vault:secret/data/app#field`	HashiCorp Vault (KV v1/v2)
`awssm:prod/stripe#field`	AWS Secrets Manager
`azkv:my-vault/secret-name#field`	Azure Key Vault
`gsm:projects/p/secrets/s/versions/latest#field`	GCP Secret Manager
`env:NAME`	process environment — self-hosted / dedicated deployments only

#field selects a key out of a JSON secret; omit it to take the whole value. Configure your managers in Settings → Secret managers; your references resolve only against your organization's own managers. A provider-scheme reference that can't resolve fails closed (the action fails rather than dispatching a blank credential).

env: is self-hosted only

env: reads a variable from the platform's own environment, so it is available only on self-hosted deployments. On the hosted platform it is rejected — use a secret-manager reference (vault: / awssm: / azkv: / gsm:) instead.

Credential broker — minting scoped credentials

Besides acting through Provenant (invoke), an agent can request a scoped, short-lived credential bound to one authorized action (mintCredential) and use its own tooling with it. Which provider mints is a per-connector broker profile (Govern → Connectors → Credential broker), configured with your own provider account:

Provider	What is minted	Value cap
Stripe Issuing	a single-use virtual card capped at the authorized amount	physically enforced by the card network
OAuth token exchange	an access token audience-bound to the resource	advisory (scope-bound, no money cap)
AWS STS AssumeRole	temporary AWS credentials bound to the resource ARN + explicit `metadata.iamActions`	advisory (IAM-scoped, no money cap)

Broker mode needs no connector auth

In broker mode Provenant never calls the target itself — the agent uses the minted credential directly. A connector used only for credential minting therefore needs no Auth type and no downstream credential; it exists to carry the scope (allowed actions/resources) and the broker profile. Configure Auth only when the same connector also serves invoke / MCP calls, where Provenant performs the downstream request with a server-held credential.

On the hosted platform, minting requires a broker profile on the connector named in the request. Self-hosted deployments may instead fall back to a deployment-level broker (CREDENTIAL_BROKER). Denied or held decisions never mint; a credential is issued at most once per authorization and expires after minutes.

Reaching private / on-prem resources: the egress relay

When a connector's downstream lives in a private network, set the connector's Egress proxy to a forward proxy inside your own network. Provenant speaks standard forward-proxy semantics — absolute-URI requests for plain HTTP and CONNECT tunnels for HTTPS/mTLS (TLS stays end-to-end) — so any compliant proxy works: Squid, Envoy, a corporate proxy you already run, or the Provenant egress relay below, a tiny dependency-free one built for exactly this. Provenant only ever connects to the proxy; it resolves and reaches the private target from within, so there is no inbound firewall change and the platform never dials private addresses itself.

The proxy is required only on the hosted platform, and only for connectors targeting private addresses — a private endpoint with no egress proxy is denied (connector.egress in the decision trail). Public endpoints never need one. Self-hosted deployments run inside your network already and reach private endpoints directly, so the relay is optional there. Running the Provenant relay, its configuration, and the fail-closed guard are covered in Egress relay.