How does SF Tether actually get a token into my agent's hands — what happens under the hood?

Your agent calls a single endpoint — POST /api/broker/token — with the end user's reference and the provider you need. Tether resolves the stored connection, checks it's active, verifies the requested scopes are within what the user consented to, auto-refreshes the credential if it's expiring within 30 seconds, and returns a short-lived provider access token bound to that agent session. On a warm connection with a fresh token, this resolves at under 50ms (p50). The full audit trail — scopes requested, scopes issued, latency, outcome — is written on every call.

What stops a compromised agent from over-reaching — grabbing scopes the user never approved?

Scope policy is enforced twice: at the moment a connection is created and on every single token issuance, even if you tightened the policy after the connection was made. If an agent asks for scopes the connection doesn't hold, Tether doesn't silently drop them — it creates a scope upgrade request, notifies the end user via email with a re-auth link, and returns a requires_consent response with a consentUrl so the agent can handle it gracefully. Org-level provider allowlists and per-connection rate limits (backed by Vercel KV) add additional layers; a runaway agent loop that exceeds the rate cap gets a 429 with a Retry-After header, not silent failure.

Are the stored OAuth tokens actually encrypted, and who can see them?

Tokens are encrypted at the Drizzle column-type layer using AES-256-GCM before they ever reach Postgres. Every ciphertext is context-bound to the specific table and row it belongs to, so a leaked ciphertext for one row cannot be replayed against another. A raw SELECT in the database returns ciphertext, not plaintext — decryption only happens through the application's typed schema layer. Admin credential reveals in the dashboard are gated to admin roles and log an admin.credential_revealed audit event every time. A rotateAllCredentials operation is available for key rotation drills.

What does the audit trail look like — will it satisfy a SOC 2 auditor?

Every connection lifecycle event (created, authorized, refreshed, revoked, error, scope change) is written to an append-only tether_connection_events table with a 7-year retention policy. Every broker token issuance — including scopes requested, scopes issued, latency, and outcome — is written to tether_broker_issuance_log, retained 90 days hot. Both tables are enforced append-only at the database permission layer: UPDATE and DELETE are revoked from the application role. The dashboard's log explorer lets you filter by event type, connection, end user, provider, IP, time range, and agent session, then export the filtered slice as CSV or JSON. An org-level data export compiles the full dataset — connections, end users, scope grants, and the complete audit logs — into a signed, zipped bundle for SOC 2 reviews or GDPR data-portability requests.

How do I connect a new provider — do I need to build the OAuth flow myself?

No. Tether ships with a catalog of 25+ pre-configured providers including Google, Microsoft 365, Slack, GitHub, Notion, Linear, Salesforce, HubSpot, Jira, Zendesk, and others — each pre-loaded with OAuth 2.0 endpoints, scope catalogs, and PKCE handling. A guided setup wizard walks you through registering your OAuth app with each provider: it shows you exactly which callback URL to paste into the provider's developer portal, then stores your client credentials encrypted. For your end users, a drop-in React component — TetherConnectButton — opens the OAuth flow in a popup and fires onSuccess/onError callbacks. The consent screen shown to end users displays your app's branding, the provider's logo, and plain-English descriptions of every scope being requested, color-coded by risk level.

What happens when a token expires or a user revokes access — does my agent just break silently?

No. A background job runs every 5 minutes, finds credentials expiring within the next 15 minutes, and refreshes them proactively — so agents almost never hit an expired token. When a refresh fails permanently (the user revoked access at the provider), the connection transitions to expired, a banner appears in your dashboard with a fix-now CTA, an email goes to the end user with a magic re-auth link, and your server receives a connection.expired webhook. The re-auth link drops the user directly into the OAuth flow without requiring them to log into your app first. You can also revoke any connection programmatically via API — including a bulk panic-revoke that zeros all credentials for an org, available as both a dashboard action and a REST endpoint.

Use Cases — SF Tether

[ USE CASES / WHO BUILDS WITH TETHER ]

The API layer your agents were always missing

Whether you're shipping agentic workflows, building a multi-tenant SaaS, or hardening an enterprise AI stack — Tether handles the token vault, OAuth flows, and least-privilege enforcement so you can focus on what the agent actually does.

See the dashboard

Browse the provider catalog

PERSONA 01 — AI AGENT BUILDER

Ship an agent that hits 25+ APIs on day one — without writing a single OAuth flow

You've written the agent logic. Now every external API integration means a new developer-portal detour: register an app, manage client secrets, wire refresh token rotation, handle provider quirks. Tether compresses that to one POST /api/broker/token call. The token vault, PKCE flows, and single-flight refresh are already built.

Pre-wired provider catalog Google, Slack, GitHub, Notion, Linear, Salesforce and 20+ more — OAuth endpoints and scope catalogs are already loaded.
Short-lived tokens per agent session The broker issues a single-use, short-TTL access token bound to the calling agent — never a long-lived credential sitting in env vars.
Automatic refresh with no race conditions Concurrent agent calls to the same connection serialize through a Postgres advisory lock — exactly one provider HTTP call fires.
MCP-native Register Tether as an MCP server so Claude, OpenAI, and other frameworks can call tether.getToken or tether.startOAuth with zero glue code.

View the quickstart

Tether dashboard — connection health overview showing active API connections

Tether connections dashboard — end-user × provider matrix with status badges

PERSONA 02 — MULTI-TENANT SAAS PLATFORM

Every customer's API token stays in its own vault — at the database level

Running a platform where each customer connects their own Slack, Gmail, or Salesforce? Tether's two-layer tenancy model separates account → tenant → end-user identity. Row-level security is FORCE'd at the Postgres layer — a query with the wrong tenant context returns zero rows, not just a polite empty array.

Credential encryption at the column type Tokens are AES-256-GCM encrypted before they ever hit the database. A raw SELECT in psql shows ciphertext.
Per-tenant scope policies Define which providers and which OAuth scopes each tenant's agents may request — enforced at both connection creation and every token issuance.
GDPR offboarding in one call Revoke all connections for an end-user, zero credentials, call the provider's revoke endpoint — idempotent and fully audited.
Bulk provisioning via REST Create end-users in bulk from your CRM using the auto-generated REST surface under /api/rest/v1/tether/* with OpenAPI docs.

Explore connections

PERSONA 03 — ENTERPRISE / COMPLIANCE TEAM

Every token issuance is on the record before your auditors ask

SOC 2 and GDPR reviews live or die on evidence. Tether's append-only audit tables — partitioned by month, retained by policy — give your security team a filterable, exportable timeline of every connection event and every broker issuance, with no manual logging required.

Full issuance log

Every broker token mint records: scopes requested, scopes issued, latency, outcome, IP hash, and the agent session ID. Append-only at the DB role level — no UPDATE or DELETE permitted.

GDPR-aligned by default

Consent interstitials log accepted/declined before any OAuth redirect. IP addresses are SHA-256 hashed. Data-portability export compiles connections + audit trail into a signed, zipped bundle on demand.

Admin credential reveal is itself audited

Revealing a masked token from the connection detail page writes an admin.credential_revealed event. Auditors see who looked, when, and from which session.

Tether audit log explorer — unified timeline of connection events and broker issuances

The logs explorer auditors actually use

A unified, virtualized timeline of tether_connection_events and tether_broker_issuance_log — filtered by event type, connection, end-user, provider, IP, or time range. Click any row to expand the full JSON metadata. Export the filtered slice as CSV or JSON for your IR team.

Filter by provider, scopes, or individual agent session

PERSONA 04 — PLATFORM OPERATOR / INFRA LEAD

Keep agents on a leash — even as they acquire new capabilities

Agents that can call any API, anytime, at any scope level, are a liability. Tether's policy engine enforces provider allowlists and scope limits at both connection creation and every token issuance — even if the policy was tightened after the connection was made.

STEP 01 — ALLOWLIST
Define which APIs agents may touch
Toggle providers on and off, set the exact OAuth scopes allowed per provider, and mark high-risk scopes as requiring human approval before a connection can be created.
STEP 02 — RATE LIMIT
Cap per-connection and per-key issuance rates
Set requests-per-minute, daily issuance caps, and per-API-key limits. When a runaway agent loop fires, the rate limiter returns a 429 with Retry-After — and emits a rate_limited event before any provider quota burns.
STEP 03 — SCOPE UPGRADE
Just-in-time scope expansion with human in the loop
When an agent requests a scope the connection doesn't hold, Tether queues a scope upgrade request, notifies the end-user, and returns a consentUrl. The agent retries after the human approves — no silent escalation.
STEP 04 — PANIC
Break-glass: revoke everything in under a second
If an agent goes rogue or an admin laptop is compromised, a single confirmed action revokes all connections org-wide, calls provider revoke endpoints in parallel, and emits an org.panic_revoke audit event.

0.1s$ tether policy set --provider slack --allow-scopes channels:read,chat:write

0.3s scope policy saved — 2 scopes allowed, 14 scopes denied

0.6s admin.scope_policy.updated logged

0.2s broker.rate_limited — connection: conn_8f3a, key: sk_prod_x7

0.5s HTTP 429 — Retry-After: 12s

0.8s provider quota remaining: 100%

0.2s broker — insufficient scope: drive:write not granted

0.4s scope_upgrade_request created — user notified via email

0.9s user approved — connection now holds drive:write

0.1s POST /api/tether/admin/panic-revoke — org: acme-prod

0.4s connections revoked — provider endpoints called

0.7s audit.org.panic_revoke logged + webhook delivered

PERSONA 05 — DEVELOPER EXPERIENCE TEAM

Five minutes from SDK key to a real API call in production

Setting up OAuth for a new provider used to mean 30+ minutes per provider portal. Tether's guided setup wizard walks through the callback URL paste, credential entry, and a verification ping — for any of the 25+ providers in the catalog. Your team gets a 5-line code snippet that works.

Quickstart page with real SDK key prefilled Node, Python, and Go snippets. The 'Test it' button runs the snippet server-side and shows the live response inline.
Embeddable Connect button Drop TetherConnectButton into your app. The OAuth popup, polling, and onSuccess callback are handled.
Interactive playground Pick a connection, choose an endpoint, edit the JSON params, hit Send — Tether brokers a real token and proxies the call, showing the full response in a syntax-highlighted panel.
Onboarding tour for new orgs First-run guided walkthrough from provider catalog to SDK key to first connection to live dashboard. No staring at an empty screen.

Open the quickstart Try the playground

Tether end-users directory — searchable list with per-user connection counts

CAPABILITIES ACROSS ALL USE CASES

72 features shipped. A few that cut across every workflow.

Background token refresh

A Temporal cron checks for tokens expiring in the next 15 minutes, refreshes them with single-flight locking, and transitions failed connections to 'expired' before your agent ever sees a 401.

Webhook delivery for every state change

connection.authorized, connection.refreshed, connection.revoked, broker.token_issued — HMAC-signed events delivered to your endpoint so your system stays in sync without polling.

Provider health monitoring

A cron checks provider reachability every 10 minutes and surfaces operational/degraded/down badges in the dashboard and in the broker's X-Provider-Status response header.

BROKER / GOOGLEaccess token issued — scope: gmail.readonly0.3s

REFRESH / SLACKtoken refreshed via single-flight lock — 1 provider call1.1s

POLICY / SALESFORCEscope 'api:write' denied — tenant policy enforcement0.0s

WEBHOOK / LINEARconnection.authorized delivered — customer endpoint 2000.8s

SCOPE-UPGRADE / GITHUBrepo:write upgrade requested — end-user notified0.2s

HEALTH / NOTIONprovider status: operational — badge updated2.4s

REVOKE / ZENDESKconnection revoked — provider endpoint called + zeroed0.5s