Authentication

Credentials for the trading and data surface - what to get, where to send it.

Every production call carries a credential. Without one, trading endpoints answer 401 AUTH_REQUIRED and the streaming endpoint declines the handshake.

Credential	Header / transport	Used for
API key (tfk_test_... / tfk_live_...)	X-API-Key header	The programmatic trading path: quotes, preflight, orders, status
JWT Bearer	Authorization: Bearer <jwt>	Workspace administration: service accounts, key management, dashboards
SIWE signature	POST /api/v1/auth/challenge → /verify	Linking and authenticating wallets

Compliance-sensitive operations such as order submission may also require the X-TetraFi-Attestation header.

Getting a Key

Create a service account and issue a key from the dashboard (Workspace → Service Accounts → API Keys). Keys carry fine-grained scopes - quotes, orders, trades, settlements, treasury, compliance, and more - so a quoting integration holds only what it needs. tfk_test_ keys hit the sandbox, tfk_live_ production.

Every request passes two gates: the key’s scope and the owner’s live workspace permission, re-derived each time. Demote the owner and the key narrows immediately. Minting keys is session-only: a credential cannot create a credential.

Prove the loop on a tfk_test_ key before flipping to tfk_live_. No workspace yet? Reach the team.

Sending Credentials

REST APIs

headers = {"X-API-Key": "tfk_live_..."}

curl -H "X-API-Key: tfk_live_..." ...

WebSocket

Browsers cannot set headers on a WebSocket handshake, so pass the key as a token query parameter:

import websockets

async with websockets.connect("wss://api.tetrafi.io/api/v1/ws?token=tfk_live_...") as ws:
    ...

Beyond the Key

	What it adds
Request signing	Opt-in HMAC per key: timestamp and signature headers, a five-minute window, replays refused.
OAuth2 client credentials	A service account exchanges its key for a short-lived bearer token with the same scopes.
MFA	Authenticator apps, passkeys, recovery codes; an org-wide policy per role.
Sessions	List active sessions, revoke the others, review login activity.
Workspace selection	X-Workspace-Id scopes every call to one workspace.

None of this is wallet authority; signing from a wallet is a separate, owner-approved grant (Wallets & Signing).

Rate Limits and Key Safety

Throughput is metered per key and per workspace; ask for more headroom. A key belongs on your backend, never in client bundles, public repos, or a browser’s network tab. Leaked? Kill it in the dashboard and mint a fresh one.