Prerequisites Checklist

Before integrating the Freeq API, ensure your setup meets all requirements. Complete this checklist to avoid common integration issues.

Essential Requirements

1. Project Key

• You have received your unique project_key from the Freeq team
• Key is stored securely in your environment variables or secure configuration
• Key is accessible to your backend service during the authentication flow

Project Key Security

Your project key should never be exposed in client-side code or public repositories. Always keep it on your server-side applications only.

2. JWT Authentication System

Your user authentication system must be capable of generating JSON Web Tokens (JWTs) that meet specific requirements:

Required JWT Claims

Your JWT payload must contain these standard claims:

• iss (Issuer): Must match your registered issuer domain
• aud (Audience): Must be set to api.freeq.com
• exp (Expiration Time): Standard UNIX timestamp indicating when the token expires
• email: The user's email address (critical - used as primary identifier)

Example JWT Payload

{
  "iss": "https://your-auth-domain.com",
  "aud": "api.freeq.com",
  "exp": 1642291200,
  "email": "user@example.com",
  "sub": "user_12345"
}

3. OpenID Connect Discovery Document

Your JWT issuer domain must host a publicly accessible OIDC discovery document:

• Discovery document is publicly accessible at https://your-domain.com/.well-known/openid-configuration
• Document contains valid jwks_uri pointing to your JSON Web Key Set endpoint
• JWKS endpoint is publicly accessible and returns properly formatted keys

Example Discovery Document

{
  "issuer": "https://your-auth-domain.com",
  "authorization_endpoint": "https://your-auth-domain.com/oauth/authorize",
  "token_endpoint": "https://your-auth-domain.com/oauth/token",
  "userinfo_endpoint": "https://your-auth-domain.com/userinfo",
  "jwks_uri": "https://your-auth-domain.com/.well-known/jwks.json",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

4. JSON Web Key Set (JWKS) Endpoint

Your JWKS endpoint must meet these requirements:

• Publicly accessible without authentication
• Returns JSON object with a keys property
• Keys property is an array (even for single key)
• Contains valid RSA public key(s) for JWT signature verification

Correct JWKS Format

{
  "keys": [
    {
      "kid": "my-key-id",
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "n": "xKWKrOD_Ihrr3FHFeNwA3K...",
      "e": "AQAB"
    }
  ]
}

Common JWKS Errors

The most common error is returning a single key object instead of an array. The keys property must always be an array, even with just one key.

Wrong:

{
  "keys": {
    "kid": "my-key-id",
    "kty": "RSA",
    ...
  }
}

Correct:

{
  "keys": [
    {
      "kid": "my-key-id",
      "kty": "RSA",
      ...
    }
  ]
}

Optional Requirements

5. Webhook Endpoint (Recommended)

For real-time wallet creation notifications:

• Publicly accessible endpoint that can receive POST requests
• HTTPS enabled (required for production webhooks)
• Responds with 2xx status codes to acknowledge receipt
• URL provided to Freeq team during setup

Webhook Endpoint Requirements

// Your webhook endpoint should:
app.post('/webhooks/freeq', (req, res) => {
  try {
    // Process the webhook payload
    const { walletId, walletAddress, emailAddress } = req.body;
    
    // Update your database
    await updateUserWallet(emailAddress, walletAddress);
    
    // Always respond with 2xx status
    res.status(200).json({ received: true });
  } catch (error) {
    // Handle errors gracefully
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Processing failed' });
  }
});

6. User Info Endpoint (Optional)

Your issuer domain can optionally host a /userinfo endpoint:

• Accessible at https://your-domain.com/userinfo
• Accepts JWT in Authorization header
• Returns user profile information including name

Example UserInfo Response

{
  "sub": "user_12345",
  "email": "user@example.com", 
  "name": "John Doe",
  "email_verified": true
}

Environment Setup

Development Environment

• Test environment configured with testnet API endpoints
• Development webhook endpoint accessible (consider using ngrok for local testing)
• Environment variables configured:

  FREEQ_PROJECT_KEY=your_project_key_here
  FREEQ_API_URL=https://api.testnet.superfreeq.com
  WEBHOOK_SECRET=your_webhook_secret

Production Environment

• Production project key obtained from Freeq team
• Production webhook endpoint configured and tested
• HTTPS enabled for all webhook endpoints
• Error monitoring configured for API calls
• Logging setup for debugging authentication issues

Testing Your Setup

Validate Your JWT Configuration

Use these tools to test your JWT setup before integrating:

1. Test OIDC Discovery Document

curl https://your-domain.com/.well-known/openid-configuration

Should return valid JSON with all required endpoints.

2. Test JWKS Endpoint

curl https://your-domain.com/.well-known/jwks.json

Should return JSON with keys array containing your public key(s).

3. Validate JWT Claims

Use jwt.io to decode and validate your JWT tokens:

• Verify all required claims are present
• Check that signatures validate against your public keys
• Confirm expiration times are reasonable

4. Test API Authentication

Try a simple API call with your JWT:

curl -X POST \
  https://api.testnet.superfreeq.com/api/v1/signin \
  -H 'Authorization: Bearer YOUR_JWT_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "YOUR_PROJECT_KEY_HERE"
  }'

Expected responses:

• 200 OK: JWT valid, user exists with wallet
• 401 Unauthorized: JWT validation failed (check configuration)
• 400 Bad Request: Missing or invalid project key

Common Setup Issues

Authentication Errors (401 Unauthorized)

If you're getting 401 errors, check:

1. OIDC Discovery Document

   • Is it publicly accessible?
   • Does it contain valid jwks_uri?

2. JWKS Endpoint

   • Is it publicly accessible?
   • Is keys property an array?
   • Are key formats correct?

3. JWT Claims

   • Are all required claims present?
   • Is aud set to api.freeq.com?
   • Is email claim included?

4. JWT Signature

   • Is JWT properly signed with your private key?
   • Does public key in JWKS match your private key?

Webhook Issues

If webhooks aren't working:

1. Accessibility

   • Is your endpoint publicly accessible?
   • Are you using HTTPS in production?

2. Response Codes

   • Are you returning 2xx status codes?
   • Are you handling errors gracefully?

3. URL Configuration

   • Did you provide the correct URL to Freeq team?
   • Is the endpoint path correct?

Getting Help

Before Contacting Support

1. Complete this entire checklist
2. Test each component individually (OIDC, JWKS, JWT validation)
3. Check our troubleshooting guide for common solutions
4. Review error messages carefully - they often indicate the specific issue

When You Need Support

Include this information when contacting the Freeq team:

• Your issuer domain and OIDC discovery document URL
• Sample JWT (with sensitive data redacted)
• Specific error messages you're receiving
• Whether individual components (OIDC, JWKS) are working
• Your webhook endpoint URL (if using webhooks)

Useful Testing Tools

• jwt.io - JWT decoder and validator
• ngrok - Expose local endpoints for webhook testing
• curl or Postman - Test API endpoints manually
• OpenID Connect Debugger - Validate OIDC configuration

---

Next Steps

Once you've completed this checklist:

1. Follow the Integration Guide to implement the API calls
2. Review the REST API documentation for detailed endpoint specifications
3. Set up webhook handlers for real-time notifications
4. Test thoroughly in development before going to production

Ready to Integrate?

With all prerequisites met, you're ready to start the integration process. The Freeq API will handle the complex blockchain operations while you focus on your application logic.