Skip to main content

SecretVaults SDK TypeScript Docs

This guide shows how to get started building with the Nillion secretvaults-ts SDK for build applications with Nillion Private Storage.

Install Nillion Dependencies​

npm install @nillion/secretvaults @nillion/nuc

Builder Client Usage​

SecretVaults SDK SecretVaultBuilderClient Usage

info

Prerequisites​

Before building with the SecretVaults SDK, you need:

  1. Nillion Wallet: Create a wallet
  2. Testnet NIL: Get NIL tokens from the Nillion faucet
  3. Get a Nillion API Key with a subscription to nilDB

Initialize a Builder Client​

Initialize the client with your Nillion API Key and a valid nilDB subscription. Connect to nilDB nodes of choice. Call refreshRootToken() after initialization to obtain authentication tokens.

nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Register Builder Profile​

One-time setup to register your builder profile to the nilDB nodes. Checks if profile exists, creates one if needed, and handles duplicate registration errors.

  • did: Decentralized identifier generated from your API key
  • name: Display name that will be set for your builder profile
nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Create Collection​

Collections organize and validate your data according to the schema rules. Builders can create "standard" or "owned" collection types.

tip

You can use the Collection Explorer Tool to more easily build and validate a JSON schema for your collection.

Create Standard Collection​

nildb/secretvaults-ts/sdk-examples/standard-collections/create-standard-collection.ts
loading...

Create Owned Collection​

nildb/secretvaults-ts/sdk-examples/owned-collections/create-owned-collection.ts
loading...

Read Collections​

Gets the id, collection type, and name of all collections.

nildb/secretvaults-ts/sdk-examples/shared/read-collections.ts
loading...

Create Records​

Creates new records in a standard collection. Records must match the collection's JSON schema. Use %allot to mark fields for encryption.

  • collection: ID of the target collection
  • data: Array of record objects matching the schema
  • %allot: Special field marker that encrypts the value
tip

Use the no-code Collection Explorer Tool to view the collection and schema

The collection page has an "Example Record Payload" button that will show you the data structure for a record in the collection.

nildb/secretvaults-ts/sdk-examples/standard-collections/create-standard-record.ts
loading...

Read Records​

Finds and retrieves records from a collection using filter criteria. Use the collection explorer to view collections and records.

  • collection: ID of the collection to search
  • filter: Query object to match records (e.g., by _id or other fields)
nildb/secretvaults-ts/sdk-examples/shared/read-collection.ts
loading...

Update Records​

Updates existing records in a collection. Can modify both regular and encrypted fields using MongoDB-style update operators.

  • collection: ID of the target collection
  • filter: Query to match records for updating
  • update: Update operations using $set, $unset, etc.
nildb/secretvaults-ts/sdk-examples/standard-collections/update-record.ts
loading...

Delete Records​

Deletes records from a collection based on filter criteria. Use the collection explorer to verify deletions.

  • collection: ID of the target collection
  • filter: Query to match records for deletion
nildb/secretvaults-ts/sdk-examples/standard-collections/delete-record.ts
loading...

Create Delegation Token​

Creates a delegation token that allows a user client to perform operations on behalf of a builder client. Delegation tokens enable secure, time-limited access without sharing the builder's root credentials.

  • audience(userDid): Specifies which user DID can use this token
  • expiresAt: Unix timestamp when the token becomes invalid
  • build(): Signs the token with the builder's private key
nildb/secretvaults-ts/sdk-examples/owned-collections/create-delegation-token.ts
loading...

User Client Usage​

SecretVaults SDK SecretVaultUserClient Usage

Generate a New User Keypair​

Creates a new cryptographic keypair for user authentication and generates the corresponding decentralized identifier (DID).

nildb/secretvaults-ts/sdk-examples/nuc-helpers.ts
loading...

Initialize a User Client​

Initialize the user client with their user keypair or get their Keypair from the user's private key.

nildb/secretvaults-ts/sdk-examples/client-helpers.ts
loading...

Create Owned Records​

Creates user-owned records with access control permissions. Unlike standard records, owned records have explicit ownership and can grant specific access rights to other users.

  • owner: User ID that owns the data
  • data: Array of record objects
  • acl: Access control list defining permissions for other users (in this case the granteeDid)
  • delegationToken: Token from the builder allowing the user to perform the operation on the builder's collection
nildb/secretvaults-ts/sdk-examples/owned-collections/create-owned-data.ts
loading...

List Owned Records​

Retrieves a list of all data references owned by the user client, showing which collections contain the user's data.

  • listDataReferences(): Returns all data references for the authenticated user
  • collection: ID of the collection containing the user's data
  • document/record: ID of the specific record owned by the user
  • builderClient: ID of the builder client that created the collection
nildb/secretvaults-ts/sdk-examples/owned-collections/list-owned-records.ts
loading...

Read Owned Record​

Retrieves a specific owned record by its ID from a collection. Only the record owner or users with granted read access can retrieve the data.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to retrieve
  • readData(): Fetches the record data with decrypted fields
nildb/secretvaults-ts/sdk-examples/owned-collections/read-owned-record.ts
loading...

Delete Owned Record​

Deletes a specific owned record from a collection. Only the record owner can delete their data.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to delete
  • deleteData(): Removes the record from the collection permanently
nildb/secretvaults-ts/sdk-examples/owned-collections/delete-owned-record.ts
loading...

Grant Access​

Grants specific permissions to another user for accessing an owned record. The record owner can control read, write, and execute permissions.

  • grantee: DID of the user receiving access permissions
  • read/write/execute: Boolean flags for specific permission types
  • collection: ID of the collection containing the record
  • document: ID of the specific record to grant access to
nildb/secretvaults-ts/sdk-examples/owned-collections/grant-access.ts
loading...

Revoke Access​

Removes previously granted permissions from a user for accessing an owned record. Only the record owner can revoke access permissions.

  • collection: ID of the collection containing the record
  • document: ID of the specific record to revoke access from
  • grantee: DID of the user whose access is being revoked
  • revokeAccess(): Removes all permissions for the specified user
nildb/secretvaults-ts/sdk-examples/owned-collections/revoke-access.ts
loading...

Integration Examples​

Standard Collection Example​

Complete workflow demonstrating standard collection operations: creating a collection, adding multiple records, updating data, deleting records, and viewing the final state.

Full Example Code
nildb/secretvaults-ts/sdk-examples/standard-collections/full-example-standard.ts
loading...

Owned Collection Example​

Complete example demonstrating the full workflow for owned data collections: creating a user, delegation tokens, owned collections, and data with access control.

Full Example Code
nildb/secretvaults-ts/sdk-examples/owned-collections/full-example-owned.ts
loading...

Full SDK Reference Docs​

Complete TypeScript documentation for all methods and types is available at: https://nillion.pub/secretvaults-ts/modules.html

SecretVaultBuilderClient​

  • Class for standard data collections with comprehensive CRUD operations and collection management.

  • Key Methods: createCollection, createStandardData, findData, updateData, deleteData, register, readProfile, refreshRootToken, createQuery, runQuery

SecretVaultUserClient​

  • Class for user-owned data collections with data access control and permissions.

  • Key Methods: createData, readData, deleteData, grantAccess, revokeAccess, listDataReferences, readProfile

Available Types​

The SDK includes comprehensive TypeScript types for all requests, responses, and data structures.