Skip to content

Authentication and scopes

Key kinds

  • Publishable keys are origin-bound and intended for browser applications.
  • Secret keys are server credentials and must never be exposed to a browser.
  • Both key kinds are stored as salted hashes. The full value is shown only at creation.
  • Test and live credentials are separate. Live credentials require production approval.

Send a secret key as Authorization: Bearer …. Send a publishable key as x-torq-publishable-key: ….

Wallet sessions

Wallet-scoped resources and actions require an opaque x-torq-wallet-session token. A challenge binds the application, wallet, chain, browser origin, nonce, and expiry. Challenges are single-use; sessions are short-lived and revocable.

Developer Console sessions

The private-preview Developer Console uses a separate wallet-first session boundary. An active organization member signs an origin-bound, single-use challenge; the browser receives an opaque session only as an HttpOnly, SameSite=Strict cookie. The cookie value is never exposed to the frontend client, and Torq stores only a hash. Console requests revalidate the exact origin, organization status, member wallet, active membership, expiry, and revocation state from Postgres.

Create each preview organization with an ownerWalletAddress. Keep at least two active owners: Torq cannot recover or bypass a lost owner wallet.

Approved-role workflows

Torq revalidates all of the following when a workflow is prepared and again before execution:

  • application scope
  • current wallet identity
  • chain
  • entity binding
  • canonical role and permission projection
  • required onchain or timelock authority
  • canonical snapshot freshness

Scope examples

wallet:read
bind wallet-scoped reads to the current opaque session
positions:read
wallet-scoped positions
eligibility:read
wallet eligibility and admission state
funds:read
distressed recovery fund catalogue and holdings reads
workflows:prepare
prepare typed transaction intents
workflows:track
register externally submitted transactions
events:read
event history and cursor replay
webhooks:write
manage webhook endpoints
sandbox:write
reset application-owned sandbox fixtures
role:borrower
prepare borrower role workflows

Scope checks fail closed. Application grants, key grants, wallet-session grants, and canonical role authority must all agree.