# Key concepts & glossary

A quick reference for the terms used across the docs, ordered from the most everyday to the most technical.

## People & access

| Term | Definition |
| --- | --- |
| **Human user** | A person who logs into the vault with an SSO account (Google) and a WebAuthn passkey. Human users perform administrative tasks: configuring policies, managing keys, and reviewing audit logs. |
| **Machine User** | An automated process that calls the vault API. Identified by an Ed25519 public key and an API key. Machine Users sign every mutating request with their Ed25519 private key. They are subject to the same Administrative Policy and Signing Policy as human users. |
| **Agent** | An AI agent is a specific kind of Machine User: a large language model or autonomous software system that calls the vault on behalf of a business process. Agents are first-class identities with full policy, freeze, and audit coverage. See [For AI agents](/introduction/for-ai-agents) and the [AI agent guide](/develop/connect-ai-agent). |
| **Group** | A flat, named collection of human users and Machine Users. Groups are the unit of policy: Administrative Policy rules grant actions to groups, and Signing Policy rules filter requests by the group the requester belongs to. A user can belong to multiple groups. |
| **Setup Admin** | A human user designated during deployment. Setup Admins complete the first-login bootstrap ceremony, enroll their passkeys, and form the initial Admins group. They are the only identities with any permissions before the first Administrative Policy is configured. |
| **Passkey** | A hardware-backed WebAuthn credential enrolled on a specific device (Face ID, Touch ID, or a security key). Every human user must have at least one. Every state-changing operation requires a passkey assertion. Passkeys are phishing-resistant: they are bound to the vault's origin and cannot be reused on a different site. |

## Keys & venues

| Term | Definition |
| --- | --- |
| **Key** | A secret cryptographic key managed by the vault. The vault supports HMAC-SHA256, HMAC-SHA384, HMAC-SHA512, Ed25519, and RSA 4096 keys. The raw secret material is never accessible to any user or operator. |
| **Key version** | Keys support multiple versions. The first import or generation is version 0. Rotation creates version N+1. Signing defaults to the latest version; you can target a specific version when needed. Versions are permanent: they are never deleted when you rotate. |
| **Security group** | A named collection of keys. Security groups are used as filters in Signing Policy rules ("this rule applies to keys in group X"). A key must belong to a security group to be governed by a Signing Policy. See [Security groups](/guide/keys/security-groups). |
| **Venue** | A named external counterparty: an exchange, OTC desk, or custodian. Each venue defines the signing scheme it expects (e.g., HMAC-SHA256 for Binance, Ed25519 for another exchange) and the encoding it uses for keys. Keys are always associated with a venue. Venues are pre-seeded for 18 major exchanges; you can add custom venues. |
| **Environment** | A free-form string label on a key (for example, `prod`, `staging`, or `testnet`). Used for filtering and organization. Not enforced by the vault. |
| **Recovery kit** | An encrypted archive of all key shares. Exported from the Backup modal in the web app, or via `GET /v1/keys-backup`. Encrypted with RSA-OAEP-SHA-256 + ChaCha20-Poly1305 using a public key configured at deployment. Required for disaster recovery. Each Key Store node has a distinct backup key. |

## Policy

| Term | Definition |
| --- | --- |
| **Administrative Policy** | The policy that controls who can perform which vault actions. Replaces role-based access control. Rules map user groups to actions. Deny by default. See [Administrative Policy](/guide/admin-policy/understanding). |
| **Signing Policy** | The policy that controls how keys may be used to sign. An ordered list of rules evaluated top to bottom; the first match wins. Each rule specifies which users, which keys, and what action to take (Approve, Deny, or External Rule Server). Deny by default. See [Signing Policy](/guide/signing-policy/understanding). |
| **Rule** | One entry in a policy. For Administrative Policy: a mapping of a user group to an action. For Signing Policy: a combination of user group filter, key security group filter, optional conditions, and a result. |
| **Condition** | A filter within a Signing Policy rule. Conditions narrow when the rule matches. The current supported condition is `raw_signing` (the request is a raw byte payload, not a decoded venue operation). || **External Rule Server (ERS)** | An advanced Signing Policy result type. Instead of Approve or Deny, the vault calls a customer-operated HTTP service and uses its signed response as the verdict. This allows custom logic (time-of-day rules, cross-system checks) without modifying the vault itself. Requires writing, deploying, and maintaining a service alongside the vault. |

:::warning\[ERS requires engineering work]
The External Rule Server is an advanced integration. It requires you to write and operate a separate HTTP service that returns signed verdicts. This is not a point-and-click configuration. Involve engineering before selecting this option.
:::

## Operations

| Term | Definition |
| --- | --- |
| **Freeze** | A runtime kill switch that blocks signing. You can freeze at several scopes: a specific key, all keys for a venue, a specific user (blocking all their signing), all users in a group, or the entire system. Freeze takes effect immediately, interrupting in-flight requests. A reason is required. Governed by Administrative Policy. |
| **Audit event** | A structured, append-only log entry produced by every vault operation. Records the actor (human or machine), the action, the target resource, and the outcome. Queryable and exportable for SIEM ingestion. |

## Cryptography

### Multi-Party Computation (MPC)

Multi-Party Computation is a family of cryptographic protocols that let a group of parties jointly compute a function over their private inputs without any party revealing its input to the others.

In the vault, MPC is used for two purposes:

**Distributed key generation (DKG).** Instead of generating a key in one place and then splitting it, the three Key Store nodes run a DKG protocol. The output is three key shares, one per node, with no party ever holding the full key. The correctness guarantee: any two nodes can combine their shares to produce a valid signature. The security guarantee: an attacker holding fewer than two shares learns nothing about the key.

**Threshold signing.** When a signing request is approved, the three Key Store nodes run a distributed signing protocol. Each node uses its local share. The output is a standard, verifiable signature. No node sees the full key during this process.

The vault uses a 2-of-3 threshold. This means:

* Security: an attacker must compromise 2 of 3 nodes.
* Availability: the loss of any 1 node does not prevent signing.

### Threshold signature schemes

A threshold signature scheme (TSS) splits a secret key into N shares such that any T of them can produce a valid signature, but T-1 shares reveal nothing. The vault uses:

* **DKLs23 (based on DKLs19/DKLS)** for ECDSA (secp256k1), a scheme built on oblivious transfer.
* **FROST** (RFC 9591) for Ed25519 (EdDSA), a round-optimized Schnorr threshold scheme.

The resulting signatures are identical to those a standard single-party key would produce. Verifiers on exchanges, blockchains, and other systems need no knowledge that MPC was involved.

### HMAC and key-sharing for API secrets

Exchange API secrets are HMAC keys. HMAC (Hash-based Message Authentication Code) is a symmetric authentication primitive: the key is shared between the exchange and the key holder. The exchange uses it to verify that a request was signed by the legitimate holder.

Importing an HMAC secret into the vault uses a specialized key-sharing protocol, not standard MPC DKG. The browser shards the raw secret into encrypted shares using the Sodot HMAC key-sharing SDK and sends each share directly to a Key Store node. The secret never traverses the Orchestrator or any other component. The vault can then compute HMAC signatures collaboratively across the three Key Store nodes using garbled circuits.

### Key refresh and proactive security

Over time, a determined attacker might attempt to collect key shares one by one. Proactive security (key refresh) counters this by periodically re-randomizing all shares. After a refresh, old shares and new shares cannot be combined, so any previously-captured share becomes useless. The underlying key does not change: existing signatures remain valid and the public key is unchanged.

### Communication security

All inter-node communication within the MPC cluster uses end-to-end encrypted and authenticated channels established during the DKG ceremony. The relay server that coordinates messages between nodes is explicitly untrusted: a compromised relay can cause downtime but cannot compromise key material.