Vaulty API

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

## Sections
• [Vaulty API](https://docs.vaulty.xyz/vaulty-api.md): 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.
  • [API Health Status](https://docs.vaulty.xyz/vaulty-api/authenticate-api-calls-copy-1.md): The API Health Status section provides users with real-time information on the operational status of the API. By checking this section, users can verify the health and availability of the API, ensuring smooth functioning of their applications that rely on it. This section enables users to proactively monitor and respond to any potential issues with the API to maintain optimal performance.
  • [Authenticate API calls](https://docs.vaulty.xyz/vaulty-api/authenticate-api-calls.md): API Key Authentication (Client Level) All API requests must include a valid API key in the request headers. The API key identifies the client application and is used for rate limiting and access control. API Key is passed in the request headers using the key x-api-key Bearer Token Authentication (User Level) For protected endpoints, users must authenticate using Bearer tokens obtained through the authentication flow. Bearer token is passed in the request headers using the key Authorization: Bearer <token> Recovery Token Authentication (Identity Recovery) For identity recovery operations, a special recovery token is required in the header. Basic Bearer token is not needed Recovery token is passed in the request using the key x-id-recovery-token
  • [API Errors](https://docs.vaulty.xyz/vaulty-api/api-errors.md): Vaulty uses a standardized error response format across all endpoints: JSON { "error": { "errorCode": 10001, "message": "AUTHENTICATION_REQUIRED", "description": "Client and user authentication is required for this operation." }, "errorType": "UNAUTHORIZED" } Error Types: NOT_FOUND (403): Access denied FORBIDDEN (403): Access denied UNAUTHORIZED (401): Authentication required VALIDATION_ERROR (400): Invalid request data CONFLICT (409): Resource conflict API ERROR (500): Internal API Error, if those appear please notify us Common Error Codes: 10001 : Authentication required 10002 : Invalid key 10003 : Value required 10004 : Type mismatch 10005 : Invalid phone number 10006 : Invalid email 20001 : Token not found 20002 : Access denied 30001 : Cannot update deleted token
  • [Security Considerations](https://docs.vaulty.xyz/vaulty-api/security-considerations.md): All sensitive data is encrypted using format-preserving encryption (FPE) API keys and tokens have configurable expiration times Comprehensive audit logging for all operations Rate limiting to prevent abuse CORS protection for web applications Input validation and sanitization Secure token storage and transmission
  • [Compliance](https://docs.vaulty.xyz/vaulty-api/compliance.md): GDPR-compliant data handling Audit trails for regulatory requirements Data retention policies Access control and authorization Encryption at rest and in transit
• [Authentication](https://docs.vaulty.xyz/authentication.md): The Authentication module handles user identity verification through multi-factor authentication challenges. Key Features: SMS and Email verification Configurable challenge length and expiration JWT token generation and refresh Rate limiting and security controls Authentication Flow Diagram:
  • [Initiate phone number authentication challenge](https://docs.vaulty.xyz/authentication/initiate-phone-number-authentication-challenge.md): Initiate phone number challenge verification
  • [Initiate email authentication challenge](https://docs.vaulty.xyz/authentication/initiate-email-authentication-challenge.md)
  • [Verify authentication challenge](https://docs.vaulty.xyz/authentication/verify-authentication-challenge.md)
• [User](https://docs.vaulty.xyz/authentication-copy.md): 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. Key Features: Phone and Email authentication method update Access to Phone and Email PII via user authorization and Format Preserving encryption versions.
  • [Get user details](https://docs.vaulty.xyz/authentication-copy/verify-authentication-challenge-copy-1.md)
  • [Start phone number linking](https://docs.vaulty.xyz/authentication-copy/get-user-details-copy-2.md)
  • [Start email linking](https://docs.vaulty.xyz/authentication-copy/get-user-details-copy-1-1.md)
  • [Verify linking authentication challenge](https://docs.vaulty.xyz/authentication-copy/get-user-details-copy.md)
• [Tokenization](https://docs.vaulty.xyz/cold-storage.md): The Tokenization module provides secure data encryption and storage with configurable access levels and recovery requirements. Key Features: Format-preserving encryption (FPE) Multiple access levels (NORMAL, RECOVERY_REQUIRED) Audit logging for all operations Metadata support for data classification We are constantly working to expand Format Preserving Encryption. Be aware that Vaulty will expand its offering capabilities. Tokenization Flow Diagram:
  • [Tokenize data](https://docs.vaulty.xyz/cold-storage/tokenize-data.md)
  • [List tokens with filters](https://docs.vaulty.xyz/cold-storage/list-tokens-with-filters.md): 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. Note: Metadata filtering is currently limited ot 1 level deep
  • [Get token by ID](https://docs.vaulty.xyz/cold-storage/get-token-by-id.md)
  • [Update token data](https://docs.vaulty.xyz/cold-storage/update-token-data.md)
  • [Soft delete token](https://docs.vaulty.xyz/cold-storage/soft-delete-token.md)
  • [Detokenize data by token ID](https://docs.vaulty.xyz/cold-storage/detokenize-data-by-token-id.md)
• [Identity Recovery](https://docs.vaulty.xyz/identity-recovery.md): The Identity Recovery module provides a sophisticated multi-step verification system for accessing protected data. Key Features: Multi-step verification workflows Multiple verification methods (SMS, Email, PIN, Liveness) Configurable recovery processes Time-limited recovery tokens Comprehensive audit trail Identity Recovery Flow Diagram: Recovery Process Configuration:
  • [Identity Recovery Methods](https://docs.vaulty.xyz/identity-recovery/identity-recovery-methods.md): Liveness and Passkeys recovery methods are currently as early access for testing purposes.
    • [Create identity recovery method](https://docs.vaulty.xyz/identity-recovery/identity-recovery-methods/create-identity-recovery-method.md): Sandbox / Testing For testing purposes on non produciton client / environments livness recovery method can be bypassed by providing the following json request body in this inital request. JSON { "value": "bypass", "type": "liveness" } Right after Verfiy Link Challenge request can be called to finalized the cahllenge roundtrip.
    • [Get all identity recovery methods](https://docs.vaulty.xyz/identity-recovery/identity-recovery-methods/get-all-identity-recovery-methods.md)
    • [Verify linking challenge](https://docs.vaulty.xyz/identity-recovery/identity-recovery-methods/verify-linking-challenge.md)
  • [Start identity recovery attempt](https://docs.vaulty.xyz/identity-recovery/identity-recovery-attemps/start-identity-recovery-attempt.md)
  • [Trigger identity recovery challenge step](https://docs.vaulty.xyz/identity-recovery/identity-recovery-attemps/trigger-identity-recovery-challenge-step.md): Sandbox / Testing For testing purposes on non produciton client / environments livness recovery method can be bypassed by providing the following json request body in this inital request. JSON { "value": "bypass", "type": "liveness" } Right after Verfiy Link Challenge request can be called to finalized the cahllenge roundtrip.Insert line topInsert line below
  • [Validate identity recovery attempt](https://docs.vaulty.xyz/identity-recovery/identity-recovery-attemps/validate-identity-recovery-attempt.md)
  • [Verify identity recovery challenge step](https://docs.vaulty.xyz/identity-recovery/identity-recovery-attemps/verify-identity-recovery-challenge-step.md)
  • [Get identity recovery attempt flow](https://docs.vaulty.xyz/identity-recovery/identity-recovery-attemps/get-identity-recovery-attempt-flow.md)
  • [Create identity recovery flow](https://docs.vaulty.xyz/identity-recovery/create-identity-recovery-flow.md)
  • [Get identity recovery flow](https://docs.vaulty.xyz/identity-recovery/get-identity-recovery-flow.md)
• [Federated Identity](https://docs.vaulty.xyz/federated-identity.md): 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. The Federated Identities API 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 Federated Buckets — containing multiple user identities and their corresponding wallet derivations. Core Concepts Federated Buckets A Federated Bucket represents a logical container for identities belonging to a single client or domain. Each bucket has: A unique bucketId An associated secretKey used for HMAC signing and secure wallet operations Lifecycle management endpoints to create, delete, and rotate keys Federated Identities A Federated Identity represents a user record within a bucket. It encapsulates: External references (like user ID, email, phone) Cryptographic wallet derivations following BIP44/BIP49 and SLIP44 specifications Optional custom metadata Wallets Each identity contains a Hierarchical Deterministic (HD) wallet , 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> API Endpoints Overview 1. Create a Bucket POST /v1/federated-identities Creates a new federated bucket. Body Example: JSON { "bucketId": "main-bucket" } Response: JSON { "id": "123e4567-e89b-12d3-a456-426614174000", "bucketId": "main-bucket", "isActive": true, "secretKey": "abc123", "createdAt": "2024-01-20T12:00:00Z", "updatedAt": "2024-01-20T12:00:00Z" } Errors 403: Federated identities not enabled for client 409: Bucket already exists 2. Get Bucket Details GET /v1/federated-identities/{bucketId} Retrieves information about a specific bucket. 3. Delete a Bucket DELETE /v1/federated-identities/{bucketId} Deletes a bucket only if it has no existing identities . 4. Rotate Secret Key POST /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. Managing Identities 5. Create an Identity POST /v1/federated-identities/{bucketId}/identities Creates a new identity under a bucket. Body Example: JSON { "externalId": "user-external-123", "phoneNumber": "+1234567890", "email": "user@example.com", "mnemonic": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about", "metadata": { "displayName": "John Doe" } } Response Example: JSON { "id": "123e4567-e89b-12d3-a456-426614174000", "identityId": "user-123", "externalId": "user-external-123", "phoneNumber": "+1234567890", "email": "user@example.com", "wallet": { "address": "0xc9621e34c4968cb6d201a1db944303e48d3297e3", "publicKey": "0xc9621e34c4968cb6d201a1db944303e48d3297e31a1db944303e48d3297e3", "chainInfo": { "coinType": "60", "family": "EVM", "name": "Ethereum", "symbol": "ETH", "derivationPath": "m/44'/60'/0'/0/0" } }, "metadata": { "displayName": "John Doe" }, "createdAt": "2024-01-20T12:00:00Z", "updatedAt": "2024-01-20T12:00:00Z" } 6. List Identities GET /v1/federated-identities/{bucketId}/identities?page=0&limit=20 Retrieves all identities under a given bucket with pagination. 7. Get Identity Details GET /v1/federated-identities/{bucketId}/identities/{identityId} Returns detailed information about a specific identity. Query Parameters: bipSpec – (Required) BIP version, supports 44 or 49 coin – (Required) Coin type per SLIP44 (e.g., 60 for Ethereum) derivationPath – (Required) Account path (e.g., 0-0-0) 8. Update Identity PUT /v1/federated-identities/{bucketId}/identities/{identityId} Updates phone number, email, or metadata of an identity. 9. Delete Identity DELETE /v1/federated-identities/{bucketId}/identities/{identityId} Soft deletes an identity from the bucket. Wallet Operations 10. Retrieve Wallet Details GET /v1/federated-identities/{bucketId}/identities/{identityId}/wallet Fetches the derived public key and address for an identity. 11. Sign a Message POST /v1/federated-identities/{bucketId}/identities/{identityId}/wallet/sign Signs an arbitrary message using the identity’s wallet. This operation requires HMAC signature validation . Security Model 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. Request Example: Plain text { "message": "0x47576443337a4ff2d53fd", "timestamp": "1761583382233", "nonce": "7b5f6a9f01c6a", "hmac_signature": "173ac40fb6ac57cc7524594c523bea1bdd54836a" } Response Example: JSON { "signature": "0x1234567890abcdef...", "message": "0x47576443337a4ff2d53fd", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb", "signatureType": "ECDSA", "chainInfo": { "coinType": "60", "family": "EVM", "name": "Ethereum", "symbol": "ETH", "derivationPath": "m/44'/60'/0'/0/0", "bipSpec": "44" } } Errors 401: HMAC validation failed 404: Identity not found