Authentication

Learn how to authenticate with the AuxVault API.

Overview

AuxVault uses API Key authentication for all server-to-server integrations (ERP, payment processing, automation). Every request requires two headers:

x-api-key: YOUR_API_KEY
X-Tenant-ID: YOUR_TENANT_ID

Important: Both headers are required on every request — missing either one returns a 401 Unauthorized response.

API Key Types

AuxVault issues three distinct key types. Use the right key for the right purpose:

Luqra ERP Integration: Use an lv_erp_ key for all ERP operations. Pass X-Merchant-ID: MERCHANT_ID on calls that target a specific merchant — no separate per-merchant keys required.

Payment Processing (SDK / PCI server): Use the lv_pk_ processing key for a merchant. This key is scoped to one merchant+gateway and is used by the AuxVault SDK and PCI tokenization server. It is auto-created when the merchant's VAR sheet is saved.

Your Credentials

API Key format: lqv_live_sk_... (production) or lqv_test_sk_... (development)
Tenant ID format: a slug like acme-payments or a UUID like 550e8400-e29b-41d4-a716-446655440000

Step 1: Test Your Connection

Before writing integration code, verify your credentials:

curl -X POST https://dev.auxcore.net/api/v1/public/testConnection \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

Success response (200 OK):

{
  "success": true,
  "message": "Connection successful",
  "data": {
    "platform": "AuxVault",
    "version": "2.0.0",
    "tenantId": "acme-payments",
    "merchantId": "merchant-456",
    "timestamp": "2026-02-23T14:00:00.000Z"
  }
}

If you receive a 401, double-check both headers are present and correct.

Step 2: Process a Payment

With credentials confirmed, process a transaction:

curl -X POST https://dev.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 125.00,
    "SuggestedMode": "Card",
    "CardNumber": "4111111111111111",
    "ExpiryMonth": "12",
    "ExpiryYear": "2027",
    "CVV": "123",
    "BillingCustomerName": "John Doe",
    "BillingEmail": "john@example.com",
    "BillingAddress": "123 Main St",
    "BillingCity": "New York",
    "BillingState": "NY",
    "BillingPostalCode": "10001"
  }'

Creating an API Key (Dashboard)

1. Log in to the AuxVault dashboard
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Enter a name (e.g., ERP Integration - Production)
5. Set permissions and optional expiry
6. Copy the key — it is only shown once

Warning: Store the API key securely. It cannot be retrieved after creation. If lost, revoke and create a new one.

Creating an API Key (Programmatically)

# You need a valid JWT token first — see "JWT Token (Dashboard)" below
curl -X POST https://dev.auxcore.net/api/v1/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "YOUR_MERCHANT_ID",
    "name": "ERP Integration Key",
    "permissions": ["transactions.read", "transactions.write", "refunds.write", "customers.read", "customers.write"],
    "expiresInDays": 365
  }'

Response:

{
  "success": true,
  "data": {
    "id": "key_abc123",
    "name": "ERP Integration Key",
    "key": "lqv_live_sk_1234567890abcdef...",
    "permissions": ["transactions.read", "transactions.write", "refunds.write"],
    "createdAt": "2026-02-23T00:00:00Z"
  }
}

Warning: The API key is only shown in this response. Save it immediately.

JWT Token (Dashboard Operations)

For operations that require user-level authentication (managing API keys, users, settings), obtain a short-lived JWT:

curl -X POST https://dev.auxcore.net/api/v1/public/accesstoken \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourcompany.com",
    "password": "your-secure-password"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "user-123",
      "email": "admin@yourcompany.com",
      "role": "merchant",
      "merchantId": "merchant-456"
    }
  }
}

Use the JWT in the Authorization: Bearer header:

curl https://dev.auxcore.net/api/v1/merchants/merchant-456 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Tenant-ID: YOUR_TENANT_ID"

JWTs expire after 24 hours. To get a new one without re-entering credentials:

curl -X POST https://dev.auxcore.net/api/v1/public/refreshToken \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "YOUR_REFRESH_TOKEN" }'

Authentication Summary

Permission Scopes

When creating API keys, grant only the permissions your integration needs:

Error Responses

Missing API Key

{
  "success": false,
  "error": "API key required",
  "message": "Please provide a valid API key in the x-api-key header or request body"
}

Invalid API Key

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been deactivated"
}

Missing Tenant ID

{
  "success": false,
  "error": {
    "code": "TENANT_REQUIRED",
    "message": "X-Tenant-ID header is required"
  }
}

Expired JWT

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Security Best Practices

✅ DO:

• Store API keys in environment variables, never in source code
• Use HTTPS for all API calls (enforced)
• Grant minimum required permissions to each key
• Set expiry dates on API keys (rotate every 90 days)
• Use separate keys for development and production

❌ DO NOT:

• Commit API keys to version control
• Log API keys in plain text
• Share keys between environments
• Use a production API key for testing
• Expose keys in client-side JavaScript

Next Steps

• Make your first API call →
• Process transactions →
• View all endpoints →
• Error handling →

Need help? Contact support@auxvault.com