Authentication

The Fluence Behavioral Intelligence API uses API Key authentication to secure access to all production endpoints. Our multi-tier authentication system supports various subscription levels with different credit allocations, rate limits, and feature access.

Overview

• Authentication Method: API Key via X-API-Key header
• Multi-Language Support: Separate authentication for Portuguese and English APIs
• Key Management: AWS API Gateway Usage Plans with credit-based billing
• Plans Available: Essentials, Professional, and Enterprise tiers
• Security: API keys are tied to specific usage plans, rate limits, and geographic regions

API Key Requirements by Environment

Production Environments (Authentication Required)

API	Base URL	Region	Authentication
Portuguese CRM	https://a7qq5h74ej.execute-api.us-west-2.amazonaws.com/production	AWS US-West-2	X-API-Key required
English Analysis	https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production	AWS US-West-2	X-API-Key required

Development Environment (Optional Authentication)

Environment	Base URL	Authentication
Development/Testing	http://localhost:8000	Optional (mock data available)

Getting Your API Key

1. Contact Sales & Choose Your Plan

Email support@tryfluence.tech with:

Required Information

📧 Email: support@tryfluence.tech
📋 Include: Your use case, expected monthly volume, preferred language (PT/EN), and subscription tier
🌍 Geographic Focus: Brazilian market (Portuguese API) or Global (English API)
⏱️ Response Time: 24 hours for production keys

2. Available Subscription Tiers

Tier	Monthly Credits	Cost	API Key Sample	Rate Limit	Best For
Essentials	500	$29/month	basic_api_2vX9mKpQ4nR8sL7fD3wE1gH6	5 req/sec	Small teams, basic CRM
Professional	1,000	$99/month	bi41LFw9Q8alZqm3fmtDA2xv941sSqIM5VgNc5f3	10 req/sec	Growing businesses
Enterprise	1,000	$299/month	complete_api_5rX8mKpQ4nR3sL7fD9wE1gH2	15 req/sec	Large organizations

3. Credit Packages (Pay-Per-Use)

For users who prefer on-demand pricing:

Package	Credits	Cost	Best For
Starter Pack	100	$19	Testing and evaluation
Power Pack	200	$49	⭐ Most popular
Enterprise Boost	500	$99	Medium volume projects
Mega Pack	1,000	$149	High volume usage

Authentication Format

Header Requirements

All production API requests must include:

X-API-Key: your-api-key-here
Content-Type: application/json

Authentication Header

Always use X-API-Key (not Authorization) for Fluence API requests. This ensures compatibility across all endpoints and geographic regions.

Quick Start Examples

Portuguese CRM API

curl -X POST "https://a7qq5h74ej.execute-api.us-west-2.amazonaws.com/production/crm_basico" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bi41LFw9Q8alZqm3fmtDA2xv941sSqIM5VgNc5f3" \
  -d '{
    "primeiro_nome": "João",
    "ultimo_nome": "Silva",
    "empresa": "Microsoft Brasil"
  }'

English Analysis API

curl -X POST "https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production/analyze" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: bi41LFw9Q8alZqm3fmtDA2xv941sSqIM5VgNc5f3" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "company": "Microsoft",
    "language": "en"
  }'

Development/Testing (No Authentication)

curl -X POST "http://localhost:8000/analyze-comprehensive" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "company": "Microsoft",
    "tier": "basic",
    "allow_mock_data": true
  }'

Programming Language Examples

Python with Requests

import requests
import os

# Set up authentication
headers = {
    'Content-Type': 'application/json',
    'X-API-Key': os.getenv('FLUENCE_API_KEY')
}

# Portuguese CRM API
response = requests.post(
    'https://a7qq5h74ej.execute-api.us-west-2.amazonaws.com/production/crm',
    headers=headers,
    json={
        'primeiro_nome': 'Maria',
        'ultimo_nome': 'Santos',
        'empresa': 'Google Brasil'
    }
)

if response.status_code == 200:
    result = response.json()
    print(f"MBTI Type: {result['analise']['mbti_type']}")
    print(f"Credits Used: {result['billing_info']['creditos_utilizados']}")
else:
    print(f"Error: {response.status_code} - {response.text}")

JavaScript/Node.js with Axios

const axios = require('axios');

const analyzeProfile = async () => {
  try {
    const response = await axios.post(
      'https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production/analyze',
      {
        first_name: 'John',
        last_name: 'Doe',
        company: 'Apple',
        language: 'en'
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': process.env.FLUENCE_API_KEY
        }
      }
    );
    
    console.log('OCEAN Scores:', response.data.analise.ocean_scores);
    console.log('Credits Remaining:', response.data.billing_info.creditos_restantes);
  } catch (error) {
    console.error('API Error:', error.response?.data || error.message);
  }
};

analyzeProfile();

Go with HTTP Client

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type AnalysisRequest struct {
    FirstName string `json:"first_name"`
    LastName  string `json:"last_name"`
    Company   string `json:"company"`
    Language  string `json:"language"`
}

func main() {
    apiKey := os.Getenv("FLUENCE_API_KEY")
    
    request := AnalysisRequest{
        FirstName: "John",
        LastName:  "Doe",
        Company:   "Microsoft",
        Language:  "en",
    }
    
    jsonData, _ := json.Marshal(request)
    
    req, _ := http.NewRequest("POST", 
        "https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production/analyze",
        bytes.NewBuffer(jsonData))
    
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)
    
    client := &http.Client{}
    resp, err := client.Do(req)
    
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }
    defer resp.Body.Close()
    
    fmt.Printf("Status: %s\n", resp.Status)
}

Rate Limits & Performance

Rate Limits by Subscription Tier

Tier	Requests/Second	Burst Limit	Concurrent Requests	Monthly Quota
Essentials	5 req/sec	10 requests	5	500 requests
Professional	10 req/sec	20 requests	10	1,000 requests
Enterprise	15 req/sec	30 requests	10	1,000 requests

Performance by Analysis Tier

Analysis Tier	Response Time	Complexity	Credit Cost
Basic	2-5 seconds	Profile analysis only	1 credit
Standard	5-10 seconds	Profile + posts analysis	1-2 credits
Premium	10-15 seconds	Full ML analysis + buyer playbooks	2 credits

Credit Monitoring & Billing

Real-Time Credit Tracking

Each API response includes detailed billing information:

{
  "analise": {
    // Analysis data here
  },
  "billing_info": {
    "creditos_utilizados": 2,
    "creditos_restantes": 998,
    "tipo_plano": "professional",
    "renovacao_proxima": "2025-02-15T00:00:00Z",
    "limite_mensal": 1000,
    "uso_percentual": 0.2
  }
}

Credit Cost by Endpoint

Endpoint	Credits	Best Use Case
Basic CRM (/crm_basico)	1	Lead qualification
Complete CRM (/crm)	2	Detailed prospect analysis
Standard Analysis (/analyze)	1	General behavioral insights

| Health Check (/health, /saude) | 0 | API validation |

Enhanced Error Handling

Authentication Errors

Invalid API Key (401)

{
  "success": false,
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided",
    "code": 401,
    "user_action": "Verify your API key is correct and active",
    "support_contact": "support@tryfluence.tech"
  }
}

Insufficient Credits (402)

{
  "success": false,
  "error": {
    "type": "insufficient_credits",
    "message": "Not enough credits to complete request",
    "code": 402,
    "credits_needed": 2,
    "credits_available": 0,
    "user_action": "Purchase additional credits or upgrade your plan",
    "upgrade_url": "mailto:support@tryfluence.tech?subject=Credit%20Upgrade%20Request"
  }
}

Rate Limit Exceeded (429)

{
  "success": false,
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before making another request",
    "code": 429,
    "retry_after": 60,
    "current_limit": "10 requests/second",
    "user_action": "Wait 60 seconds or upgrade to a higher tier for increased limits"
  }
}

Security Best Practices

🔒 API Key Security

Security Notice

Your API key provides access to your account and should be treated as a password. Never share it publicly or commit it to version control.

Best Practices:

• ✅ Store in environment variables or AWS Secrets Manager
• ✅ Use different keys for different environments (dev/staging/prod)
• ✅ Rotate keys regularly (contact support for rotation)
• ✅ Monitor usage through analytics dashboard
• ✅ Use HTTPS only for all API requests

Security Anti-Patterns:

• ❌ Hardcode in source code or configuration files
• ❌ Commit to Git repositories or version control
• ❌ Include in client-side JavaScript or mobile apps
• ❌ Share in URL parameters or query strings
• ❌ Log API keys in application logs

Environment Variable Setup

# .env file
FLUENCE_API_KEY=bi41LFw9Q8alZqm3fmtDA2xv941sSqIM5VgNc5f3
FLUENCE_PORTUGUESE_URL=https://a7qq5h74ej.execute-api.us-west-2.amazonaws.com/production
FLUENCE_ENGLISH_URL=https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production

# Python with python-dotenv
from dotenv import load_dotenv
import os

load_dotenv()

api_key = os.getenv('FLUENCE_API_KEY')
portuguese_base_url = os.getenv('FLUENCE_PORTUGUESE_URL')
english_base_url = os.getenv('FLUENCE_ENGLISH_URL')

Health Checks & Validation

Test API Key Without Using Credits

Portuguese API Health Check

curl -X GET "https://a7qq5h74ej.execute-api.us-west-2.amazonaws.com/production/saude" \
  -H "X-API-Key: your-api-key-here"

English API Health Check

curl -X GET "https://ax9l103wsj.execute-api.us-west-2.amazonaws.com/production/health" \
  -H "X-API-Key: your-api-key-here"

Health Check Response

{
  "status": "healthy",
  "service": "fluence-behavioral-intelligence-api",
  "version": "2.1.0",
  "timestamp": "2025-01-15T10:30:00Z",
  "api_key_status": "valid",
  "subscription_info": {
    "tier": "professional",
    "credits_remaining": 847,
    "monthly_limit": 1000,
    "reset_date": "2025-02-01T00:00:00Z",
    "rate_limit": "10 req/sec"
  },
  "rate_limit_status": {
    "requests_remaining": 598,
    "reset_time": "2025-01-15T11:00:00Z"
  },
  "endpoints_available": [
    "/crm_basico",
    "/crm", 
    "/analyze",
    ""
  ]
}

Troubleshooting

Common Issues & Solutions

Issue	Possible Cause	Solution
401 Unauthorized	Invalid API key	Verify key is correct and active
402 Payment Required	Insufficient credits	Purchase credits or upgrade plan
429 Rate Limited	Too many requests	Implement backoff strategy
404 Not Found	Wrong endpoint URL	Check base URL and endpoint path
500 Server Error	Temporary service issue	Retry with exponential backoff

Debug Checklist

1. ✅ Verify API key is correctly formatted
2. ✅ Check X-API-Key header (not Authorization)
3. ✅ Confirm you're using the correct base URL
4. ✅ Validate request JSON format
5. ✅ Check credit balance via health endpoint
6. ✅ Monitor rate limit headers in responses

Support & Resources

• 📧 Technical Support: support@tryfluence.tech
• 💳 Billing & Upgrades: sales@tryfluence.tech
• 🔍 API Playground: Test your authentication →
• 📊 Analytics Dashboard: Monitor usage and performance
• 📚 Documentation: Complete endpoint guides in sidebar

---

Next Steps

1. Get your API key → - Contact sales for immediate access
2. Test in playground → - Validate your setup interactively
3. Explore CRM endpoints → - Start with basic lead qualification
4. View pricing & tiers → - Compare plans and features

Ready to authenticate? Contact sales → or test live →