CONCEPTS

Core concepts

Tesska replaces “copy the secret to whoever needs it” with “lend out access instead”: credentials live in vaults, callers (projects) hold scoped keys, and the broker exchanges grants for short-lived access. These eight concepts cover the whole product.

Concepts at a glance

The one-line version of each — details in the sections below.

  • Credential — a secret, login, or OAuth connection you place in custody; each one is either mode A (direct) or mode B (approval-gated).
  • Vault — the container a credential lives in, defining its security semantics; typed as normal / hot / cold.
  • Workspace — the tenant boundary: team, members, and every resource hang off a workspace.
  • Project — a caller: an app, script, or CI job that needs access.
  • Scoped key — a project's Bearer credential, prefixed tsk_, issued in the console's Token Center.
  • Grant — the line connecting project × credential × scopes, with a token TTL cap and a per-minute rate limit.
  • Approval — mode B's human-in-the-loop: every call is pushed to the owner's phone for consent.
  • Audit — full metadata records of every brokered call, never containing plaintext.

Credentials: mode A vs. mode B

Every credential belongs to one mode, which decides the server's role when the broker exchanges it for access.

  • Mode A (direct) — platform-held: stored with envelope encryption (AES-256-GCM), the server can decrypt, and a call matching a grant is exchanged for a short-lived token immediately. Best for credentials that must automate 24/7.
  • Mode B (approval-gated) — zero-knowledge: encrypted in your browser, the server stores ciphertext only; every call is pushed to the owner's phone for approval, then delivered end-to-end encrypted to the caller. Best for high-sensitivity credentials.
  • Mode A delivers short-lived tokens by default; raw credential delivery requires an explicit per-asset setting plus a global switch (off by default).

Vaults: normal / hot / cold

A vault is the container credentials live in. Today the security level is set per credential (mode A/B); vault types are available — pick a type when creating the vault, and every credential inside inherits its unlock and callability rules, with nothing to configure per item.

  • Normal — server-side envelope encryption, callable by grants at any time; for website logins, API keys, and other everyday automation credentials.
  • Hot — also server-side, but must be unlocked before any outbound call (auto-supplied by a third-party escrow, or entered by hand).
  • Cold — zero-knowledge, encrypted in the browser, and never participates in outbound calls — no path can broker it out; for seed phrases, private keys, and top secrets, with single-signer unlock; M-of-N multi-sig coming soon.

Workspaces, projects, and scoped keys

On the storage side the hierarchy is workspace → vault → credential; on the access side it's workspace → project → scoped key. A project embodies one caller: give your deploy script, CI, and backend service a project each, so each holds its own key and none can overreach.

  • Scoped keys are issued in the console's Token Center, prefixed tsk_, and used as the Bearer for every /v1/* endpoint.
  • A key only works for the credentials and scopes it was granted — GET /v1/grants lists what this key can use, GET /v1/platforms lists available platforms.
  • Project-level platform allowlist: a project can only reach platforms on its list.
  • Third-party apps can also obtain per-user, revocable scoped keys via Connect Tesska (OAuth authorization code with mandatory PKCE), usable as a Bearer the same way.

Grants: project × credential × scopes

A grant is the smallest unit of permission: which project, using which credential, within which scopes. Without a grant, even a valid key exchanges for nothing.

  • Every grant carries a token TTL cap and a per-minute rate limit.
  • Credentials can be frozen or revoked with one click, instantly cutting off every grant beneath them.
  • Anomaly detection runs continuously on the call stream, pushing alerts on suspicious behavior.

Approvals and audit

Every mode-B call is an act of consent brokerage: request metadata is pushed to the owner's phone, and on approval the credential is decrypted in the owner's browser and sealed to the caller's ephemeral public key (ECDH-P256 + HKDF-SHA256 + AES-256-GCM). The server never sees plaintext at any point.

  • Callers poll GET /v1/approvals/:id for the result; on approval, the returned resultCt is ciphertext only the caller's private key can open.
  • The audit trail records metadata only (who, when, which project, which grant, what outcome) — never credential plaintext.
  • Outbound webhooks are not live yet (planned); poll for approval results in the meantime.

A minimal call

With one project scoped key, a single POST shows where the two modes diverge:

curl https://tesska.com/v1/login \ -H "Authorization: Bearer tsk_..." \ -H "Content-Type: application/json" \ -d '{"platform":"github","account":"deploy-bot","scope":["repo:read"]}' # A-mode credential -> short-lived token, never the raw secret # { "token":"...", "expiresAt":"2026-07-05T13:00:00Z", "scopes":["repo:read"] } # B-mode credential -> approval pushed to the owner's phone # { "kind":"pending_approval", "requestId":"req_...", "expiresAt":"..." }

Callers never receive raw secrets by default.Mode A delivers short-lived access tokens; mode B requires the owner's approval on every delivery and is end-to-end encrypted, with zero plaintext on the server. Raw delivery requires an explicit per-asset setting plus a global switch (off by default).