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)
References
Updated 12 days ago