Skip to main content

​
Authentication

AxonVault implements a multi-layer authentication model designed for production-grade security. This guide explains each authentication layer and when to use them.
Security First: AxonVault APIs are designed for server-to-server communication. Never expose API credentials in client-side code.

​
Authentication Layers

AxonVault uses three authentication layers depending on the operation type:
LayerPurposeUsed For
API Key + HMACServer authenticationAll Server Wallet API calls
JWT Access TokenUser sessionEmbedded Wallet SDK calls
Wallet Auth TokenSigning authorizationTransaction signing operations

​
Layer 1: API Key Authentication (Server Wallets)

For server-to-server communication, use HMAC-signed requests with your API credentials.

​
Credentials

When you create an API key in the dashboard, you receive:
  • Client Key: Public identifier (safe to log)
  • Secret Key: Private key for signing (never expose)

​
Request Signing

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

​
Signature Generation

The signature is computed over a canonical string: 
{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY}

import crypto from 'crypto';

function signRequest(method, path, body, secretKey) {
  const timestamp = new Date().toISOString();
  const bodyStr = body ? JSON.stringify(body) : '';
  
  const payload = `${method}\n${path}\n${timestamp}\n${bodyStr}`;
  
  const signature = crypto
    .createHmac('sha256', secretKey)
    .update(payload)
    .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' }, secretKey);

​
Example Request

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 Wallet"}'

​
Layer 2: JWT Access Token (Embedded Wallets)

For user-facing applications, users authenticate via social login and receive JWT tokens. The Embedded Wallet SDK handles all token management automatically.

​
Social Login Flow

​
Authenticate User with SDK

The SDK handles authentication and token management automatically: 
import { AxonVaultEmbedded } from '@axonvault/embedded-wallet-sdk';

const axonVault = new AxonVaultEmbedded({
  projectId: 'proj_abc123'
});

// Authenticate user - SDK handles token storage and refresh
const user = await axonVault.authenticate({
  provider: 'google',
  idToken: googleIdToken
});

console.log('User authenticated:', user.userId);
// SDK automatically stores and refreshes tokens

​
Token Management

The SDK handles token management automatically:
  • Automatic Storage: Tokens stored securely (httpOnly cookies in browser)
  • Automatic Refresh: Tokens refreshed before expiration
  • Error Handling: Automatic retry on token expiration
You don’t need to manually manage tokens. All SDK methods are automatically authenticated: 
// SDK automatically includes tokens in requests
const wallet = await axonVault.getOrCreateWallet({
  walletName: 'My Wallet'
});

// No manual token management needed

SDK Authentication Guide

Learn more about SDK authentication methods

​
Supported Providers

ProviderStatusID Token Source
Google✅ LiveGoogle Sign-In
Apple✅ LiveSign in with Apple
Email OTP✅ LiveAxonVault Email Service

​
Layer 3: Wallet Auth Token (Signing Operations)

For sensitive operations like signing transactions, an additional wallet-level authorization is required. The SDK handles this automatically for embedded wallets.

​
When Required

  • Signing transactions
  • Transferring assets
  • Approving token spending
  • Any operation that changes on-chain state

​
How It Works

The Wallet Auth Token binds the signing request to:
  • The specific wallet
  • The exact transaction payload
  • A short time window

​
SDK Handling

For embedded wallets, the SDK automatically handles wallet auth tokens: 
// SDK automatically includes wallet auth token when signing
const txHash = await wallet.sendTransaction({
  to: '0x1234...',
  amount: '1000000000000000000',
  chainId: 'eip155:8453'
});

// No manual wallet auth token management needed
For server wallets, wallet auth tokens are handled automatically by the server-side SDK. See the Server Wallet API documentation for details.

​
API Key Types

AxonVault supports different API key types for different use cases:
TypePermissionsUse Case
LiveFull accessProduction environment
TestFull access (testnet only)Development and testing
Read-OnlyRead operations onlyAnalytics and monitoring

​
Key Permissions

You can restrict API keys to specific operations: 
{
  "name": "Analytics Key",
  "keyType": 3,
  "permissions": [
    "wallets:read",
    "transactions:read",
    "assets:read"
  ]
}
Available permissions:
  • wallets:read, wallets:write
  • transactions:read, transactions:write
  • assets:read
  • policies:read, policies:write
  • webhooks:read, webhooks:write

​
Error Responses

Authentication errors follow a consistent format: 
{
  "errorType": "unauthorized",
  "errorMessage": "Invalid signature"
}

​
Common Error Codes

Error TypeHTTP StatusDescription
unauthorized401Invalid or missing credentials
token_expired401Access token has expired
signature_mismatch401HMAC signature doesn’t match
wallet_auth_required401Wallet Auth Token required
wallet_auth_invalid401Wallet Auth Token is invalid
forbidden403Insufficient permissions

​
Security Best Practices

  • Store Secret Keys in secure vaults (AWS Secrets Manager, HashiCorp Vault)
  • Never commit credentials to version control
  • Rotate API keys regularly (recommended: every 90 days)
  • Use separate keys for development and production
  • Always use HTTPS
  • Validate timestamp freshness (reject requests older than 5 minutes)
  • Implement request idempotency for write operations
  • Log all authentication attempts for audit
  • Store refresh tokens securely (encrypted at rest)
  • Implement token refresh before expiration
  • Clear tokens on user logout
  • Never expose tokens in URLs or logs

​
SDK Authentication

Our official SDKs handle authentication automatically: 
import { AxonVault } from '@axonvault/sdk';

const client = new AxonVault({
  clientKey: 'ak_live_abc123',
  secretKey: 'sk_live_xyz789'
});

// SDK handles signing automatically
const wallet = await client.wallets.create({
  walletName: 'Treasury'
});

​
Next Steps

Create Your First Wallet

Follow the quickstart guide

Policy Engine

Set up transaction approval rules