Vaulty

Vaulty API

API Health Status

Authenticate API calls

API Errors

Security Considerations

Compliance

Authentication

Initiate phone number challenge verification

Initiate phone number authentication challenge

Initiate email authentication challenge

Verify authentication challenge

User

Get user details

Start phone number linking

Start email linking

Verify linking authentication challenge

Tokenization

Tokenize data

List tokens with filters

Get token by ID

Update token data

Soft delete token

Detokenize data by token ID

Identity Recovery

Identity Recovery Methods

Identity Recovery Attemps

Create identity recovery flow

Get identity recovery flow

Federated Identity

Federated identities

Default

Vaulty API Docs

Developer-first secure data vault API that encrypts, stores, and operates on sensitive data using layered security architecture.

Production

Sandbox

<p class="slate-p " >Welcome to the Vaulty API! This guide is intended for client developers integrating with Vaulty to securely manage, tokenize, and access sensitive data.</p><p class="slate-p " >The Vaulty API section provides users with the ability to securely store and manage sensitive information, such as credit card details or personal data. By utilizing this API, users can easily encrypt and store sensitive data, ensuring data security and compliance with industry standards.</p><p class="slate-p " ></p>

Welcome to the Vaulty API! This guide is intended for client developers integrating with Vaulty to securely manage, tokenize, and access sensitive data.

The Vaulty API section provides users with the ability to securely store and manage sensitive information, such as credit card details or personal data. By utilizing this API, users can easily encrypt and store sensitive data, ensuring data security and compliance with industry standards.

<p class="slate-p " >The Authentication module handles user identity verification through multi-factor authentication challenges.</p><p class="slate-p " ><strong class="slate-bold">Key Features:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">SMS and Email verification</div></li><li class="slate-li " ><div style="position:relative">Configurable challenge length and expiration</div></li><li class="slate-li " ><div style="position:relative">JWT token generation and refresh</div></li><li class="slate-li " ><div style="position:relative">Rate limiting and security controls</div></li></ul><p class="slate-p " ><strong class="slate-bold">Authentication Flow Diagram:</strong></p><div style="text-align:center"><figure ><div style="display:inline-block"><img src="https://d24lr4zqs1tgqh.cloudfront.net/5f0180d4-2857-4c9e-a7b1-af57ceaaf78f.png" alt="" style="
              width:494px;
	            height:434px;
	            aspect-ratio:494 / 434"
         /></div></figure></div><p class="slate-p " ></p>

The Authentication module handles user identity verification through multi-factor authentication challenges.

<p class="slate-p " >The User module handles user identifiers, authentication methods. Through it, user can modify their authentication methods as well as check the current one active.</p><p class="slate-p " >Modifying or adding anotehr Authentication method also modifies / adds an equivalent recovery method.</p><p class="slate-p " ><strong class="slate-bold">Key Features:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Phone and Email authentication method update</div></li><li class="slate-li " ><div style="position:relative">Access to Phone and Email PII via user authorization and Format Preserving encryption versions.</div></li></ul><p class="slate-p " ></p><p class="slate-p " ></p>

The User module handles user identifiers, authentication methods. Through it, user can modify their authentication methods as well as check the current one active.

Modifying or adding anotehr Authentication method also modifies / adds an equivalent recovery method.

<p class="slate-p " >The Tokenization module provides secure data encryption and storage with configurable access levels and recovery requirements.</p><p class="slate-p " ><strong class="slate-bold">Key Features:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Format-preserving encryption (FPE)</div></li><li class="slate-li " ><div style="position:relative">Multiple access levels (NORMAL, RECOVERY_REQUIRED)</div></li><li class="slate-li " ><div style="position:relative">Audit logging for all operations</div></li><li class="slate-li " ><div style="position:relative">Metadata support for data classification</div></li></ul><div style="width:100%;
	min-width:100%;" class="callout-widget" data-type=info ><div class="callout-icon"><svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M10.0628 14.1676C10.2434 14.1676 10.3927 14.1086 10.5107 13.9905C10.6288 13.8725 10.6878 13.7232 10.6878 13.5426V9.77177C10.6878 9.6051 10.6253 9.46274 10.5003 9.34469C10.3753 9.22663 10.2295 9.1676 10.0628 9.1676C9.88227 9.1676 9.73296 9.22663 9.61491 9.34469C9.49685 9.46274 9.43783 9.61205 9.43783 9.7926V13.5634C9.43783 13.7301 9.50033 13.8725 9.62533 13.9905C9.75033 14.1086 9.89616 14.1676 10.0628 14.1676ZM10.0003 7.62594C10.1948 7.62594 10.358 7.56344 10.4899 7.43844C10.6219 7.31344 10.6878 7.15371 10.6878 6.95927C10.6878 6.76482 10.6219 6.59816 10.4899 6.45927C10.358 6.32038 10.1948 6.25094 10.0003 6.25094C9.80588 6.25094 9.64269 6.32038 9.51074 6.45927C9.3788 6.59816 9.31283 6.76482 9.31283 6.95927C9.31283 7.15371 9.3788 7.31344 9.51074 7.43844C9.64269 7.56344 9.80588 7.62594 10.0003 7.62594ZM10.0003 18.3343C8.81977 18.3343 7.72255 18.1225 6.70866 17.6989C5.69477 17.2752 4.81283 16.6884 4.06283 15.9384C3.31283 15.1884 2.72602 14.3065 2.30241 13.2926C1.8788 12.2787 1.66699 11.1815 1.66699 10.0009C1.66699 8.83427 1.8788 7.74399 2.30241 6.7301C2.72602 5.71621 3.31283 4.83427 4.06283 4.08427C4.81283 3.33427 5.69477 2.74399 6.70866 2.31344C7.72255 1.88288 8.81977 1.6676 10.0003 1.6676C11.167 1.6676 12.2573 1.88288 13.2712 2.31344C14.285 2.74399 15.167 3.33427 15.917 4.08427C16.667 4.83427 17.2573 5.71621 17.6878 6.7301C18.1184 7.74399 18.3337 8.83427 18.3337 10.0009C18.3337 11.1815 18.1184 12.2787 17.6878 13.2926C17.2573 14.3065 16.667 15.1884 15.917 15.9384C15.167 16.6884 14.285 17.2752 13.2712 17.6989C12.2573 18.1225 11.167 18.3343 10.0003 18.3343ZM10.0003 17.0843C11.9448 17.0843 13.6114 16.3898 15.0003 15.0009C16.3892 13.612 17.0837 11.9454 17.0837 10.0009C17.0837 8.05649 16.3892 6.38982 15.0003 5.00094C13.6114 3.61205 11.9448 2.9176 10.0003 2.9176C8.05588 2.9176 6.38921 3.61205 5.00033 5.00094C3.61144 6.38982 2.91699 8.05649 2.91699 10.0009C2.91699 11.9454 3.61144 13.612 5.00033 15.0009C6.38921 16.3898 8.05588 17.0843 10.0003 17.0843Z" fill="#3960B4"></path></svg></div><div ><p class="slate-p " >We are constantly working to expand Format Preserving Encryption. Be aware that Vaulty will expand its offering capabilities.</p></div></div><p class="slate-p " ><strong class="slate-bold">Tokenization Flow Diagram:</strong></p><div style="text-align:left"><figure ><div style="display:inline-block"><img src="https://d24lr4zqs1tgqh.cloudfront.net/ee627dc7-61e8-4ec8-8acb-bb18578de42c.png" alt="" style="
              width:1256px;
	            height:1103px;
	            aspect-ratio:1256 / 1103"
         /></div></figure></div><p class="slate-p " ></p>

The Tokenization module provides secure data encryption and storage with configurable access levels and recovery requirements.

External key provided by the client to identify the token

Second external reference provided by the client

externalId

value

expectedType

Predefined value to group similar data for exhaustive validation

predefinedTemplateKey

Value that established the access level for the token

accessLevel

List of recoveryFlows to bind the tokens to

identityRecoveries

metaData

Foreign Key for developer associated to the given token & user.

clientId

createdAt

deletedAt

Secondary External key provided by the client to identify the token

Foreign Key for the user associated to the given token.

userId

tokenValue

updatedAt

<p class="slate-p " >Fetch tokens for a given user. The endpoint supports a filtering of token object keys as query params. It also supports querying by identity recovery flow ids as a list of ids and metadata nested key values.
<strong class="slate-bold">Note: </strong>Metadata filtering is currently limited ot 1 level deep</p>

Fetch tokens for a given user. The endpoint supports a filtering of token object keys as query params. It also supports querying by identity recovery flow ids as a list of ids and metadata nested key values.


Metadata filtering is currently limited ot 1 level deep

Invalid request data

Token not found

<p class="slate-p " >The Identity Recovery module provides a sophisticated multi-step verification system for accessing protected data.</p><p class="slate-p " ><strong class="slate-bold">Key Features:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">Multi-step verification workflows</div></li><li class="slate-li " ><div style="position:relative">Multiple verification methods (SMS, Email, PIN, Liveness)</div></li><li class="slate-li " ><div style="position:relative">Configurable recovery processes</div></li><li class="slate-li " ><div style="position:relative">Time-limited recovery tokens</div></li><li class="slate-li " ><div style="position:relative">Comprehensive audit trail</div></li></ul><p class="slate-p " ><strong class="slate-bold">Identity Recovery Flow Diagram:</strong></p><div style="text-align:left"><figure ><div style="display:inline-block"><img src="https://d24lr4zqs1tgqh.cloudfront.net/b0acc3db-8f68-46f2-8dd5-df6134e17fb5.png" alt="" style="
              width:1785px;
	            height:1571px;
	            aspect-ratio:1785 / 1571"
         /></div></figure></div><p class="slate-p " ><strong class="slate-bold">Recovery Process Configuration:</strong></p><div style="text-align:left"><figure ><div style="display:inline-block"><img src="https://d24lr4zqs1tgqh.cloudfront.net/48b3d8fb-7d9f-4a6e-8704-be8ee19ed364.png" alt="" style="
              width:1785px;
	            height:1571px;
	            aspect-ratio:1785 / 1571"
         /></div></figure></div><p class="slate-p " ></p>

The Identity Recovery module provides a sophisticated multi-step verification system for accessing protected data.

<p class="slate-p " >The Federated Identity section enables developers to create and manage secure, encrypted identity containers—called Federated Buckets—that isolate user identities and wallet data within multi-tenant environments. This allows each client to maintain separate identity vaults, ensuring organized and secure handling of multiple user identities and their associated wallet derivations.</p><p class="slate-p " >The <strong class="slate-bold">Federated Identities API </strong>allows developers to create, manage, and securely operate identity buckets and wallets within Vaulty.</p><p class="slate-p " >This feature is designed for multi-tenant environments where each client can host their own encrypted identity vaults — called <em class="slate-italic">Federated Buckets</em> — containing multiple user identities and their corresponding wallet derivations.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h2 class="slate-h2 " ><strong class="slate-bold">Core Concepts</strong></h2><h3 class="slate-h3 " ><strong class="slate-bold">Federated Buckets</strong></h3><p class="slate-p " >A <strong class="slate-bold">Federated Bucket</strong> represents a logical container for identities belonging to a single client or domain. Each bucket has:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">A unique bucketId</div></li><li class="slate-li " ><div style="position:relative">An associated secretKey used for HMAC signing and secure wallet operations</div></li><li class="slate-li " ><div style="position:relative">Lifecycle management endpoints to create, delete, and rotate keys</div></li></ul><h3 class="slate-h3 " ><strong class="slate-bold">Federated Identities</strong></h3><p class="slate-p " >A <strong class="slate-bold">Federated Identity</strong> represents a user record within a bucket.</p><p class="slate-p " >It encapsulates:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">External references (like user ID, email, phone)</div></li><li class="slate-li " ><div style="position:relative">Cryptographic wallet derivations following <strong class="slate-bold">BIP44/BIP49</strong> and <strong class="slate-bold">SLIP44</strong> specifications</div></li><li class="slate-li " ><div style="position:relative">Optional custom metadata</div></li></ul><h3 class="slate-h3 " ><strong class="slate-bold">Wallets</strong></h3><p class="slate-p " >Each identity contains a <strong class="slate-bold">Hierarchical Deterministic (HD) wallet</strong>, which can expose public keys and addresses across supported blockchains without ever exposing the private key.</p><p class="slate-p " >Wallet derivation paths follow the format:</p><p class="slate-p " ><code class="slate-code">m/&lt;bipSpec&gt;&apos;/&lt;coin&gt;&apos;/&lt;account&gt;&apos;/&lt;change&gt;/&lt;index&gt;</code></p><p class="slate-p " ></p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h2 class="slate-h2 " ><strong class="slate-bold">API Endpoints Overview</strong></h2><h3 class="slate-h3 " ><strong class="slate-bold">1. Create a Bucket</strong></h3><p class="slate-p " ><strong class="slate-bold">POST</strong> /v1/federated-identities</p><p class="slate-p " >Creates a new federated bucket.</p><p class="slate-p " ><strong class="slate-bold">Body Example:</strong></p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
  &quot;bucketId&quot;: &quot;main-bucket&quot;
}</div></div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Response:</strong></p><div class="code-block-wrapper"  style="width:100%;min-width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
  &quot;id&quot;: &quot;123e4567-e89b-12d3-a456-426614174000&quot;,
  &quot;bucketId&quot;: &quot;main-bucket&quot;,
  &quot;isActive&quot;: true,
  &quot;secretKey&quot;: &quot;abc123&quot;,
  &quot;createdAt&quot;: &quot;2024-01-20T12:00:00Z&quot;,
  &quot;updatedAt&quot;: &quot;2024-01-20T12:00:00Z&quot;
}</div></div></code></pre></div><p class="slate-p " ></p><p class="slate-p " ><strong class="slate-bold">Errors</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">403: Federated identities not enabled for client</div></li><li class="slate-li " ><div style="position:relative">409: Bucket already exists</div></li></ul><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">2. Get Bucket Details</strong></h3><p class="slate-p " ><strong class="slate-bold">GET</strong> /v1/federated-identities/{bucketId}</p><p class="slate-p " >Retrieves information about a specific bucket.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">3. Delete a Bucket</strong></h3><p class="slate-p " ><strong class="slate-bold">DELETE</strong> /v1/federated-identities/{bucketId}</p><p class="slate-p " >Deletes a bucket <strong class="slate-bold">only if it has no existing identities</strong>.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">4. Rotate Secret Key</strong></h3><p class="slate-p " ><strong class="slate-bold">POST</strong> /v1/federated-identities/{bucketId}/rotate-key</p><p class="slate-p " >Rotates the secret key for the given bucket.</p><p class="slate-p " >Use this when a secret may have been exposed or during routine security maintenance.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h2 class="slate-h2 " ><strong class="slate-bold">Managing Identities</strong></h2><h3 class="slate-h3 " ><strong class="slate-bold">5. Create an Identity</strong></h3><p class="slate-p " ><strong class="slate-bold">POST</strong> /v1/federated-identities/{bucketId}/identities</p><p class="slate-p " >Creates a new identity under a bucket.</p><p class="slate-p " ><strong class="slate-bold">Body Example:</strong></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
  &quot;externalId&quot;: &quot;user-external-123&quot;,
  &quot;phoneNumber&quot;: &quot;+1234567890&quot;,
  &quot;email&quot;: &quot;user@example.com&quot;,
  &quot;mnemonic&quot;: &quot;abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about&quot;,
  &quot;metadata&quot;: {
    &quot;displayName&quot;: &quot;John Doe&quot;
  }
}</div></div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Response Example:</strong></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
  &quot;id&quot;: &quot;123e4567-e89b-12d3-a456-426614174000&quot;,
  &quot;identityId&quot;: &quot;user-123&quot;,
  &quot;externalId&quot;: &quot;user-external-123&quot;,
  &quot;phoneNumber&quot;: &quot;+1234567890&quot;,
  &quot;email&quot;: &quot;user@example.com&quot;,
  &quot;wallet&quot;: {
    &quot;address&quot;: &quot;0xc9621e34c4968cb6d201a1db944303e48d3297e3&quot;,
    &quot;publicKey&quot;: &quot;0xc9621e34c4968cb6d201a1db944303e48d3297e31a1db944303e48d3297e3&quot;,
    &quot;chainInfo&quot;: {
      &quot;coinType&quot;: &quot;60&quot;,
      &quot;family&quot;: &quot;EVM&quot;,
      &quot;name&quot;: &quot;Ethereum&quot;,
      &quot;symbol&quot;: &quot;ETH&quot;,
      &quot;derivationPath&quot;: &quot;m/44&apos;/60&apos;/0&apos;/0/0&quot;
    }
  },
  &quot;metadata&quot;: {
    &quot;displayName&quot;: &quot;John Doe&quot;
  },
  &quot;createdAt&quot;: &quot;2024-01-20T12:00:00Z&quot;,
  &quot;updatedAt&quot;: &quot;2024-01-20T12:00:00Z&quot;
}</div></div></code></pre></div><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">6. List Identities</strong></h3><p class="slate-p " ><strong class="slate-bold">GET</strong> /v1/federated-identities/{bucketId}/identities?page=0&amp;limit=20</p><p class="slate-p " >Retrieves all identities under a given bucket with pagination.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">7. Get Identity Details</strong></h3><p class="slate-p " ><strong class="slate-bold">GET</strong> /v1/federated-identities/{bucketId}/identities/{identityId}</p><p class="slate-p " >Returns detailed information about a specific identity.</p><p class="slate-p " ><strong class="slate-bold">Query Parameters:</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">bipSpec – (Required) BIP version, supports 44 or 49</div></li><li class="slate-li " ><div style="position:relative">coin – (Required) Coin type per SLIP44 (e.g., 60 for Ethereum)</div></li><li class="slate-li " ><div style="position:relative">derivationPath – (Required) Account path (e.g., 0-0-0)</div></li></ul><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">8. Update Identity</strong></h3><p class="slate-p " ><strong class="slate-bold">PUT</strong> /v1/federated-identities/{bucketId}/identities/{identityId}</p><p class="slate-p " >Updates phone number, email, or metadata of an identity.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">9. Delete Identity</strong></h3><p class="slate-p " ><strong class="slate-bold">DELETE</strong> /v1/federated-identities/{bucketId}/identities/{identityId}</p><p class="slate-p " >Soft deletes an identity from the bucket.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h2 class="slate-h2 " ><strong class="slate-bold">Wallet Operations</strong></h2><h3 class="slate-h3 " ><strong class="slate-bold">10. Retrieve Wallet Details</strong></h3><p class="slate-p " ><strong class="slate-bold">GET</strong> /v1/federated-identities/{bucketId}/identities/{identityId}/wallet</p><p class="slate-p " >Fetches the derived public key and address for an identity.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><h3 class="slate-h3 " ><strong class="slate-bold">11. Sign a Message</strong></h3><p class="slate-p " ><strong class="slate-bold">POST</strong> /v1/federated-identities/{bucketId}/identities/{identityId}/wallet/sign</p><p class="slate-p " >Signs an arbitrary message using the identity’s wallet.</p><p class="slate-p " >This operation <strong class="slate-bold">requires HMAC signature validation</strong>.</p><h4 class="slate-h4 " ><strong class="slate-bold">Security Model</strong></h4><p class="slate-p " >Every sign request must be authenticated using a signature computed as:</p><p class="slate-p " ><span style="color:rgb(0, 0, 0)"><code class="slate-code">HMAC_SIGNATURE = BASE64(HMAC(&lt;TIMESTAMP&gt;:&lt;NONCE&gt;:HASH256(&lt;MESSAGE&gt;)))</code></span></p><p class="slate-p " >Use the secretKey of the bucket as the HMAC key.</p><p class="slate-p " ><strong class="slate-bold">Request Example:</strong></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">Plain text</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden">{
  "message": "0x47576443337a4ff2d53fd",
  "timestamp": "1761583382233",
  "nonce": "7b5f6a9f01c6a",
  "hmac_signature": "173ac40fb6ac57cc7524594c523bea1bdd54836a"
} </textarea><code class="language-plainText keep-markup drop-tokens"></code></pre></div><p class="slate-p " ><strong class="slate-bold">Response Example:</strong></p><div class="code-block-wrapper"  style="width:100%" ><div class="code-block-header">JSON</div><pre class="slate-CodeBlockElement slate-code_block"><textarea id="publishedPageCodeblock" style="display:none !important; visibility: hidden; opacity: 0; width: 1px; height: 1px;" type="hidden"> </textarea><code class="language-json keep-markup drop-tokens"><div class="slate-code_line"><div class="slate-code_line">{
  &quot;signature&quot;: &quot;0x1234567890abcdef...&quot;,
  &quot;message&quot;: &quot;0x47576443337a4ff2d53fd&quot;,
  &quot;address&quot;: &quot;0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb&quot;,
  &quot;signatureType&quot;: &quot;ECDSA&quot;,
  &quot;chainInfo&quot;: {
    &quot;coinType&quot;: &quot;60&quot;,
    &quot;family&quot;: &quot;EVM&quot;,
    &quot;name&quot;: &quot;Ethereum&quot;,
    &quot;symbol&quot;: &quot;ETH&quot;,
    &quot;derivationPath&quot;: &quot;m/44&apos;/60&apos;/0&apos;/0/0&quot;,
    &quot;bipSpec&quot;: &quot;44&quot;
  }
}</div></div></code></pre></div><p class="slate-p " ><strong class="slate-bold">Errors</strong></p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">401: HMAC validation failed</div></li><li class="slate-li " ><div style="position:relative">404: Identity not found</div></li></ul><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><p class="slate-p " ></p><p class="slate-p " ></p>

The Federated Identity section enables developers to create and manage secure, encrypted identity containers—called Federated Buckets—that isolate user identities and wallet data within multi-tenant environments. This allows each client to maintain separate identity vaults, ensuring organized and secure handling of multiple user identities and their associated wallet derivations.

allows developers to create, manage, and securely operate identity buckets and wallets within Vaulty.

This feature is designed for multi-tenant environments where each client can host their own encrypted identity vaults — called 

 — containing multiple user identities and their corresponding wallet derivations.

 represents a logical container for identities belonging to a single client or domain. Each bucket has:

 represents a user record within a bucket.

, which can expose public keys and addresses across supported blockchains without ever exposing the private key.

Wallet derivation paths follow the format:

m/<bipSpec>'/<coin>'/<account>'/<change>/<index>

Retrieves information about a specific bucket.

 /v1/federated-identities/{bucketId}/rotate-key

Rotates the secret key for the given bucket.

Use this when a secret may have been exposed or during routine security maintenance.

 /v1/federated-identities/{bucketId}/identities

 /v1/federated-identities/{bucketId}/identities?page=0&limit=20

Retrieves all identities under a given bucket with pagination.

 /v1/federated-identities/{bucketId}/identities/{identityId}

Returns detailed information about a specific identity.

Updates phone number, email, or metadata of an identity.

Soft deletes an identity from the bucket.

 /v1/federated-identities/{bucketId}/identities/{identityId}/wallet

Fetches the derived public key and address for an identity.

 /v1/federated-identities/{bucketId}/identities/{identityId}/wallet/sign

Signs an arbitrary message using the identity’s wallet.

Every sign request must be authenticated using a signature computed as:

HMAC_SIGNATURE = BASE64(HMAC(<TIMESTAMP>:<NONCE>:HASH256(<MESSAGE>)))

Use the secretKey of the bucket as the HMAC key.

Sections