Skip to main content

​
Authentication

AxonVault uses different authentication methods depending on your integration type. This guide covers both Embedded Wallet SDK authentication and Server Wallet API authentication.

​
Authentication Methods

MethodUse CaseIntegration Type
JWT TokensUser-facing applicationsEmbedded Wallets
HMAC-Signed RequestsBackend servicesServer Wallets

​
Embedded Wallet Authentication

For consumer-facing applications, users authenticate via social login (Google, Apple, Email) and receive JWT tokens. The SDK handles all authentication logic automatically, including:
  • Social login integration
  • Token management and refresh
  • Secure token storage
  • Error handling and retry logic

​
Initialize SDK

import { AxonVaultEmbedded } from '@axonvault/embedded-wallet-sdk';

const axonVault = new AxonVaultEmbedded({
  projectId: 'proj_abc123',
  environment: 'production' // or 'development'
});

​
Authentication Flow

The SDK provides a simple authenticate() method that handles all social login complexity: 
// SDK handles Google, Apple, and Email login internally
const user = await axonVault.authenticate({
  provider: 'google', // or 'apple', 'email'
  // SDK manages all provider-specific details
});

// SDK automatically stores and refreshes tokens
// No manual token management needed

​
Token Management

The SDK automatically manages JWT tokens:
  • Automatic Refresh: Tokens are refreshed before expiration
  • Secure Storage: Tokens stored securely (httpOnly cookies in browser)
  • Error Handling: Automatic retry on token expiration

Embedded Wallet SDK

See the complete SDK documentation for authentication methods

​
Server Wallet Authentication

For backend services, use HMAC-SHA256 signed requests with API keys. This ensures request integrity and prevents replay attacks.

​
Credentials

When you create an API key, you receive:
CredentialDescriptionExample
Client KeyPublic identifierak_live_abc123
Secret KeyPrivate signing keysk_live_xyz789...
Never expose your Secret Key. Store it securely and never commit it to version control.

​
Request Headers

Every request must include these headers:
HeaderDescription
X-Access-KeyYour Client Key
X-SignatureHMAC-SHA256 signature
X-TimestampISO 8601 timestamp
Content-Typeapplication/json

​
Signature Generation

Build the canonical string to sign: 
{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY}
ComponentDescriptionExample
METHODHTTP method (uppercase)POST
PATHRequest path/v1/server/wallets
TIMESTAMPISO 8601 timestamp2024-01-15T10:30:00Z
BODYJSON request body{"walletName":"Treasury"}
Then compute the HMAC-SHA256 signature: 
const signature = HMAC-SHA256(secretKey, canonicalString).toHex()

​
Implementation Examples

import crypto from 'crypto';

const clientKey = process.env.AXONVAULT_CLIENT_KEY;
const secretKey = process.env.AXONVAULT_SECRET_KEY;

function signRequest(method, path, body = null) {
  const timestamp = new Date().toISOString();
  const bodyStr = body ? JSON.stringify(body) : '';
  
  const canonicalString = `${method}\n${path}\n${timestamp}\n${bodyStr}`;
  
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(canonicalString)
    .digest('hex');
  
  return {
    'X-Access-Key': clientKey,
    'X-Signature': signature,
    'X-Timestamp': timestamp,
    'Content-Type': 'application/json'
  };
}

// Usage
const headers = signRequest('POST', '/v1/server/wallets', { walletName: 'Treasury' });

​
Request Example

curl -X POST https://api.axonvault.io/v1/server/wallets \
  -H "X-Access-Key: ak_live_abc123" \
  -H "X-Signature: 5d41402abc4b2a76b9719d911017c592" \
  -H "X-Timestamp: 2024-01-15T10:30:00Z" \
  -H "Content-Type: application/json" \
  -d '{"walletName":"Treasury"}'

​
Timestamp Validation

Requests are rejected if the timestamp is:
  • More than 5 minutes in the past
  • In the future
This prevents replay attacks.

​
Common Errors

Error TypeStatusCause
unauthorized401Invalid credentials
signature_mismatch401Signature doesn’t match
timestamp_expired401Timestamp too old
timestamp_future401Timestamp in future
token_expired401JWT token expired

​
Best Practices

  • Use environment variables or secret managers
  • Never hardcode credentials
  • Rotate keys regularly (every 90 days)
  • Store Secret Keys securely (AWS Secrets Manager, HashiCorp Vault)
  • Always use HTTPS
  • Implement request idempotency
  • Log requests for audit (exclude signatures)
  • Validate timestamp freshness
  • Implement retry with exponential backoff
  • Handle clock skew gracefully
  • Monitor for authentication failures
  • Provide user-friendly error messages