Authentication

Overview

This document explains how to authenticate with Wield to access protected endpoints such as submitting messages. There are two authentication methods:

Farcaster L1 Authentication (using FID)
Signature-based Authentication (using wallet signature)

Use BASE_URL="https://build.wield.xyz" for Farcaster L1 and Wield L2.

Authentication Flow

1. Get Signin Message

First, request a signin message that needs to be signed:

const getSigninMessage = async (address) => {  
  const response = await fetch(  
    `${BASE_URL}/auth/v1/get-account-signin-message?address=${address}&chainId=1`,  
    {  
      method: "GET",  
      headers: {  
        "Content-Type": "application/json",  
        "API-KEY": "your-api-key"  
      }  
    }  
  );

  const data = await response.json();  
  return data.signature; // This is the message to sign  
}

2. Authentication Methods

Method A: Signature Authentication

This method provides access to all endpoints but messages stay on Wield L2:

No FID required
Works with any Ethereum wallet
Messages won't be broadcasted to Farcaster L1

const authenticateWithSignature = async (signature, address) => {  
  const response = await fetch(`${BASE_URL}/auth/v2/authenticate`, {  
    method: "POST",  
    headers: {  
      "Content-Type": "application/json",  
      "API-KEY": "your-api-key"  
    },  
    body: JSON.stringify({  
      signature,  
      address,  
      chainId: 1,  
      type: "SIGNATURE"    // Specify signature authentication  
    })  
  });

  const data = await response.json();  
  return data.accessToken;  
}

Method B: Farcaster L1 Authentication (FID)

This method allows you to broadcast messages to Farcaster L1. You need:

A registered Farcaster ID (FID)
A signer key added to your FID on-chain

const authenticateWithFID = async (signature, address, signerId) => {  
  const response = await fetch(`${BASE_URL}/auth/v2/authenticate`, {  
    method: "POST",  
    headers: {  
      "Content-Type": "application/json",  
      "API-KEY": "your-api-key"  
    },  
    body: JSON.stringify({  
      signature,  
      address,  
      chainId: 1,  
      id: signerId,    // Your signer ID registered on Farcaster  
      type: "FID"      // Specify FID authentication  
    })  
  });

  const data = await response.json();  
  return data.accessToken;  
}

Important: The signer ID must be previously registered on-chain with your FID. See Farcaster documentation for details on signer registration.

Complete Authentication Example

// Here's a complete example using ethers.js:
const authenticateUser = async (wallet, type = "signature") => {  
  try {  
    // Step 1: Get the address  
    const address = await wallet.getAddress();

    // Step 2: Get message to sign
    const message = await getSigninMessage(address);

    // Step 3: Sign the message
    const signature = await wallet.signMessage(message);

    // Step 4: Authenticate
    if (type === "FID") {
      return await authenticateWithFID(signature, address, YOUR_SIGNER_ID);
    } else {
      return await authenticateWithSignature(signature, address);
    }
  } catch (error) {  
    console.error("Authentication failed:", error);  
    throw error;  
  }  
}

Using the Access Token

Once authenticated, use the access token in subsequent requests:

const makeAuthenticatedRequest = async (accessToken) => {  
  const response = await fetch(`${BASE_URL}/your/protected/endpoint`, {  
    method: "POST",  
    headers: {  
      "Content-Type": "application/json",  
      "API-KEY": "your-api-key",  
      "Authorization": `Bearer ${accessToken}`  
    },  
    body: JSON.stringify({  
      // Your request data  
    })  
  });

  return await response.json();  
}

Security Considerations

Never expose your private keys or mnemonics
Store access tokens securely
Implement token refresh mechanisms
Use environment variables for sensitive data

Common Error Scenarios

Invalid Signer ID
- Error: "Signer not found"
- Solution: Ensure signer is registered on-chain for your FID
Invalid Signature
- Error: "Invalid signature"
- Solution: Verify the message being signed matches the one returned by the signing endpoint
Expired Token
- Error: "Token expired"
- Solution: Re-authenticate to get a new token

API Endpoints Reference

Authentication Endpoints

Get Signin Message
GET /auth/v1/get-account-signin-message
Query Parameters:
- address: Ethereum address
- chainId: Chain ID (1 for Ethereum mainnet)
Authenticate
POST /auth/v2/authenticate
Body Parameters:
- signature: Signed message
- address: Ethereum address
- chainId: Chain ID
- type: "FID" or "signature"
- id: Signer ID (required for FID authentication)