# SecretVault

### What is SecretVault[​](https://docs.nillion.com/build/secret-vault#what-is-secretvault) <a href="#what-is-secretvault" id="what-is-secretvault"></a>

Zyllion's SecretVault is a decentralized storage system that keeps sensitive data secret by storing encrypted shares across a cluster of zyl[DB nodes](https://zyllion.gitbook.io/zyllion/architecture). Each zylDB node stores a separate share of the encrypted data, ensuring no single node can reveal the original value.

This approach offers stronger security than traditional databases where all data sits in one place. Because SecretVault splits sensitive data between nodes, a breach of any single node only reveals a useless share. You need to combine multiple shares to reconstruct and decrypt the original data.

#### How it works[​](https://docs.nillion.com/build/secret-vault#how-it-works) <a href="#how-it-works" id="how-it-works"></a>

Related Zyllion tools[​](https://docs.nillion.com/build/secret-vault#related-nillion-tools)

* zyl**QL** is the library used to encrypt data into shares before storage in SecretVault and decrypt shares after retrieval
* **SecretDataAnalytics** enables executing additional queries on stored data in SecretVault without decryption

### How to use SecretVault[​](https://docs.nillion.com/build/secret-vault#how-to-use-secretvault) <a href="#how-to-use-secretvault" id="how-to-use-secretvault"></a>

Interact with zylDB APIs or the JS [secretvaults](https://zyllion.gitbook.io/zyllion/secretvault) helper package shown in the [Quickstart](https://zyllion.gitbook.io/zyllion/build/start-building) to use SecretVault (also available in Python). First complete setup by registering an organization and defining the structure of your data collections. After setup, you can securely store, retrieve, and query data from SecretVault.

#### 1. Register an Organization[​](https://docs.nillion.com/build/secret-vault#1-register-an-organization) <a href="#id-1-register-an-organization" id="id-1-register-an-organization"></a>

Register an organization to get your organization credentials and node details for the cluster of zylDB nodes where your data is securely stored.

#### 2. Define a Collection[​](https://docs.nillion.com/build/secret-vault#2-define-a-collection) <a href="#id-2-define-a-collection" id="id-2-define-a-collection"></a>

Organize your data into a collection, defined by a JSON schema that specifies fields, data types, and validation rules. Once created, the schema cannot be changed.

#### 3. Store Records[​](https://docs.nillion.com/build/secret-vault#3-store-records) <a href="#id-3-store-records" id="id-3-store-records"></a>

First, encrypt any private data fields with zylQL.

Then upload the record to all nodes in your cluster to store the record. Plaintext fields are stored identically across all nodes, while encrypted fields are split into unique shares, with each node holding one share to keep data secure.

#### 4. Retrieve Records[​](https://docs.nillion.com/build/secret-vault#4-retrieve-records) <a href="#id-4-retrieve-records" id="id-4-retrieve-records"></a>

Read or retrieve a record by fetching the data from all nodes in your cluster. Decrypt private data fields with zylQL to recombine shares from all nodes and reconstruct the original data.

### SecretVault Key Concepts[​](https://docs.nillion.com/build/secret-vault#secretvault-key-concepts) <a href="#secretvault-key-concepts" id="secretvault-key-concepts"></a>

#### Organization[​](https://docs.nillion.com/build/secret-vault#organization) <a href="#organization" id="organization"></a>

Your root entity in SecretVault. When created, receives organization credentials and details (endpoints and dids) for the cluster of nodes for storage.

#### Cluster[​](https://docs.nillion.com/build/secret-vault#cluster) <a href="#cluster" id="cluster"></a>

A group of nodes configured for your organization. All your data is stored across these nodes.

#### Node[​](https://docs.nillion.com/build/secret-vault#node) <a href="#node" id="node"></a>

An endpoint where collection data is stored. Each node in your cluster:

* Stores all plaintext field values for your collections
* Holds one share of any encrypted field value
* Is uniquely identified by its DID (Decentralized Identifier), which is required for generating API tokens and accessing the node

Nodes require API tokens for authorization. These tokens are node-specific and must be included in your requests to interact with the node.

#### Node API Tokens / Bearer Tokens[​](https://docs.nillion.com/build/secret-vault#node-api-tokens--bearer-tokens) <a href="#node-api-tokens--bearer-tokens" id="node-api-tokens--bearer-tokens"></a>

Bearer tokens, implemented as JWTs (JSON Web Tokens), are used to authenticate and authorize API calls to nodes. Each token is:

* Node-Specific: Generated for a specific node using its DID
* Secure: Signed with your organization’s private key
* Temporary: Includes an expiration time (exp) for added security

#### Collection[​](https://docs.nillion.com/build/secret-vault#collection) <a href="#collection" id="collection"></a>

A table or container of SecretVault records. Created with:

* An owner (your organization's DID)
* A schema defining the collection's structure

#### Schema[​](https://docs.nillion.com/build/secret-vault#schema) <a href="#schema" id="schema"></a>

A JSON Schema defines the immutable structure of records in a collection including:

* Field names
* Field data types (string, number, etc.)
* Required fields
* Field formats (uuid, date-time, etc.)
* Whether additional fields are allowed

#### Record[​](https://docs.nillion.com/build/secret-vault#record) <a href="#record" id="record"></a>

A single data entry that follows a collection's schema. When a record is stored:

* Every node in the cluster stores the complete record
* Unencrypted field values are identically stored in plaintext across nodes
* Encrypted field values are different on each node (each node stores a different share)

#### Field[​](https://docs.nillion.com/build/secret-vault#field) <a href="#field" id="field"></a>

A property defined in a schema. Each field has:

* A name (e.g., username, password)
* A data type (e.g., string)
* Optional formats or rules

#### Field Data[​](https://docs.nillion.com/build/secret-vault#field-data) <a href="#field-data" id="field-data"></a>

Data stored in a field. Data can be:

* Unencrypted: stored as plaintext, same value on all nodes
* Encrypted: split into shares by zylQL; each node stores a separate share
