Security

Authentication

Learn how to securely authenticate with the V-Ledger ecosystem using API Keys, OAuth 2.0, and deterministic wallets.

Environment Isolation

The V-Ledger system operates in two strictly isolated environments: Live and Sandbox. To interact with the APIs, you must always specify the environment via the x-vledger-env HTTP header.

// For Production
x-vledger-env: live

// For Testing & Staging
x-vledger-env: test

API Keys

For backend systems like SAP S/4HANA or Oracle, use standard API keys. Keys are environment-specific to prevent accidental cross-contamination.

  • Live Prefix: vk_live_...
  • Sandbox Prefix: vk_test_...

Authentication Header:

Authorization: Bearer vk_live_abc123...

Invisible Wallets

Brands and Customers don't need to manage private keys. Our Auth Service derives a deterministic EOA (Externally Owned Account) address based on their authenticated email.

  • Input: User Email + Master Secret
  • Derivation: keccak256(...)
  • Usage: Smart Account Gas Sponsorship

Passkeys (WebAuthn)

Secure passwordless login using hardware keys or biometric systems (TouchID/FaceID) via FIDO2 / WebAuthn standards.

  • Standard: Native browser cryptographic challenge-response.
  • Auto-Lockout: Once a Passkey is registered, password login is disabled.
  • Scope: Securely bound to the v-ledger.com apex domain.

Enterprise SSO

Federated identity routing for enterprise scale corporate spaces using SAML 2.0 or OpenID Connect (OIDC).

  • Domain Routing: Email-checks resolve corporate domains.
  • Integration: Connects to Microsoft EntraID, Okta, or PingIdentity.
  • Redirection: Directs clients to custom IdPs with zero configuration.

OAuth 2.0 Flow

High-volume ERP and CRM connectors use OAuth 2.0 Client Credentials flow to retrieve access tokens directly.

POST /v1/auth/oauth/token

// Request Payload
{ "client_id": "erp_client_7F28A1", "client_secret": "vsec_67B18C92eF13A0...", "grant_type": "client_credentials" }

// Response Payload
{ "access_token": "vjwt_eyJhbGciOi...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "vref_EyJhbGciOi..." }

Token Refresh Flow

Access tokens expire after exactly 1 hour. To retrieve a new one without providing client credentials again, supply the refresh_token you received.

// Request Payload
{ "grant_type": "refresh_token", "refresh_token": "vref_EyJhbGciOi..." }

// Response Payload
{ "access_token": "vjwt_eyJhbGciOi_new...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "vref_EyJhbGciOi_new..." }