Authentication

Flux uses cryptographic signatures to authenticate API requests and prove payment ownership. This ensures that only users who have paid for API access can make requests.

Overview

Authentication in Flux is based on two mechanisms:

1. Wallet Authentication — For dashboard and provider operations

2. Payment Signature Authentication — For API gateway requests

Wallet Authentication

Connecting Your Wallet

To create or manage APIs, you must connect your wallet through the dashboard.

Supported Wallets:

• MetaMask

• Coinbase Wallet

• WalletConnect

• Ledger (via WalletConnect)

Session Management

Once connected, your wallet address is used to:

• Identify you as an API provider

• Track your created APIs

• Receive payments for API calls

• Access your dashboard

Sessions are maintained via browser cookies and expire after 24 hours of inactivity.

Payment Signature Authentication

How It Works

When calling an API through the Flux gateway, you must prove that you've paid for access by providing:

1. Payment Transaction Hash — The blockchain transaction that transferred payment

2. ECDSA Signature — A cryptographic signature proving you authorized the payment

Required Headers

All gateway requests must include:

X-Payment-Tx: 0x1234567890abcdef...
X-Signature: 0xabcdef1234567890...

Generating a Signature

To generate a valid signature:

1. Create the message — Combine the API ID, transaction hash, and timestamp:

   message = apiId + txHash + timestamp

2. Sign with your private key — Use ECDSA (secp256k1):

   const message = ethers.utils.solidityKeccak256(
     ['string', 'string', 'uint256'],
     [apiId, txHash, timestamp]
   );
   const signature = await signer.signMessage(ethers.utils.arrayify(message));

3. Include in request headers — Add the signature to your API call

Example: JavaScript/Ethers.js

import { ethers } from 'ethers';

async function callAPI(apiId, endpoint, data) {
  const provider = new ethers.providers.Web3Provider(window.ethereum);
  const signer = provider.getSigner();
  
  // Assume you've already sent payment and have txHash
  const txHash = '0x...';
  const timestamp = Math.floor(Date.now() / 1000);
  
  // Create message to sign
  const message = ethers.utils.solidityKeccak256(
    ['string', 'string', 'uint256'],
    [apiId, txHash, timestamp]
  );
  
  // Sign the message
  const signature = await signer.signMessage(
    ethers.utils.arrayify(message)
  );
  
  // Make the API call
  const response = await fetch(
    `https://useflux.site/api/v2/gateway/${apiId}${endpoint}`,
    {
      method: 'POST',
      headers: {
        'X-Payment-Tx': txHash,
        'X-Signature': signature,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    }
  );
  
  return response.json();
}

Example: Python

from eth_account import Account
from eth_account.messages import encode_defunct
import requests
import time

def call_api(api_id, endpoint, data, private_key):
    account = Account.from_key(private_key)
    tx_hash = '0x...'  # Your payment transaction hash
    timestamp = int(time.time())
    
    # Create message
    message = f"{api_id}{tx_hash}{timestamp}"
    message_hash = encode_defunct(text=message)
    
    # Sign the message
    signed_message = account.sign_message(message_hash)
    
    # Make the API call
    headers = {
        'X-Payment-Tx': tx_hash,
        'X-Signature': signed_message.signature.hex(),
        'Content-Type': 'application/json'
    }
    
    response = requests.post(
        f"https://useflux.site/api/v2/gateway/{api_id}{endpoint}",
        headers=headers,
        json=data
    )
    
    return response.json()

Payment Verification

When you make a request to the gateway:

1. The gateway extracts your signature and transaction hash

2. It verifies the signature matches your wallet address

3. It checks the transaction on-chain to confirm payment

4. If valid, your request is proxied to the target API

5. If invalid, the request is rejected with a 401 error

Signature Validation

The gateway validates:

• Signature authenticity — Signature matches the message and your wallet

• Transaction existence — Transaction exists on the specified blockchain

• Payment amount — Transaction amount matches or exceeds the API's price

• Timestamp freshness — Signature timestamp is within 5 minutes

Security Best Practices

1. Never share your private key — Only use it to sign messages

2. Use HTTPS — Always communicate over encrypted connections

3. Verify API endpoints — Ensure you're calling the correct gateway URL

4. Check transaction details — Verify the payment amount before signing

5. Rotate keys regularly — Use new wallet addresses for different applications

6. Use hardware wallets — For production applications, consider hardware wallet integration

Troubleshooting

Invalid Signature Error

Problem: 401 Unauthorized - Invalid signature

Solutions:

• Verify your private key is correct

• Ensure the message format matches exactly

• Check that the transaction hash is valid

• Confirm the timestamp is recent (within 5 minutes)

Transaction Not Found

Problem: 402 Payment Required - Transaction not found

Solutions:

• Verify the transaction hash is correct

• Ensure the transaction has been mined

• Check you're using the correct blockchain

• Confirm the payment amount matches the API price

Signature Expired

Problem: 401 Unauthorized - Signature expired

Solutions:

• Generate a new signature with a current timestamp

• Ensure your system clock is synchronized

• Retry the request within 5 minutes of signing