Skip to main content
FAII uses API tokens to authenticate requests. Your API tokens carry many privileges, so be sure to keep them secure!

​
API Tokens

All API requests must include your API token in the Authorization header using Bearer authentication: 
Authorization: Bearer YOUR_API_TOKEN
Do not share your API tokens! Treat them like passwords. Never commit them to public repositories or expose them in client-side code.

​
Creating an API Token

1

Access Settings

Log into app.faii.ai and navigate to Settings
2

Go to Integrations

Click on Integrations → API
3

Generate New Token

Click Create API Token button
4

Name Your Token

Give your token a descriptive name (e.g., “Production Server”, “Development”)
5

Copy and Store

Copy the token immediately - it will only be shown once!

​
Using Your API Token

​
With cURL

curl https://app.faii.ai/api/supabase/dashboards \
  -H "Authorization: Bearer faii_token_1234567890abcdef" \
  -H "Content-Type: application/json"

​
With JavaScript

const response = await fetch('https://app.faii.ai/api/supabase/dashboards', {
  headers: {
    'Authorization': `Bearer ${process.env.FAII_API_TOKEN}`,
    'Content-Type': 'application/json'
  }
});

​
With Python

import requests
import os

headers = {
    'Authorization': f'Bearer {os.environ["FAII_API_TOKEN"]}',
    'Content-Type': 'application/json'
}

response = requests.get('https://app.faii.ai/api/supabase/dashboards', headers=headers)

​
With PHP

$headers = [
    'Authorization: Bearer ' . getenv('FAII_API_TOKEN'),
    'Content-Type: application/json'
];

$ch = curl_init('https://app.faii.ai/api/supabase/dashboards');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);

​
Token Types

FAII supports different token types for different use cases:
Token TypePrefixUse Case
Livefaii_token_Production applications
Testfaii_test_Development and testing
Restrictedfaii_restricted_Limited permissions
Test keys have full functionality but don’t affect your production data. Use them for development and testing.

​
Security Best Practices

​
Environment Variables

Store API keys in environment variables, never in code: 
# .env file
FAII_API_KEY=faii_live_1234567890abcdef

// Good ✅
const apiKey = process.env.FAII_API_KEY;

// Bad ❌
const apiKey = 'faii_live_1234567890abcdef';

​
.gitignore

Always add .env to your .gitignore: 
# .gitignore
.env
.env.local
.env.production

​
Key Rotation

Rotate your API keys regularly:
1

Create New Key

Generate a new API key in settings
2

Update Applications

Update all applications to use the new key
3

Test Thoroughly

Verify everything works with the new key
4

Delete Old Key

Once confirmed working, delete the old key
Recommended: Rotate API keys every 90 days as a security best practice.

​
Restricted Keys

For enhanced security, create restricted keys with limited permissions: 
{
  "name": "Frontend Widget",
  "permissions": ["campaigns:read", "rankings:read"],
  "rate_limit": 100,
  "allowed_ips": ["192.168.1.1", "10.0.0.1"]
}

​
Authentication Errors

​
Invalid API Key

{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid"
  }
}
Possible causes:
  • API key is misspelled
  • API key has been deleted
  • API key has expired
  • Wrong key type (test vs live)

​
Missing API Key

{
  "success": false,
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided in Authorization header"
  }
}
Solution: Ensure your request includes the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Key Permissions

{
  "success": false,
  "error": {
    "code": "insufficient_permissions",
    "message": "API key does not have permission for this operation"
  }
}
Solution: Use an API key with appropriate permissions or upgrade to a full-access key.

​
Managing API Keys

​
List All Keys

View all your API keys in the dashboard: 
Settings → API Keys
You’ll see:
  • Key name
  • Key prefix (first 8 characters)
  • Creation date
  • Last used date
  • Permissions

​
Revoke a Key

Caution: Revoking a key will immediately stop all requests using that key. Make sure no applications are actively using it.
1

Find the Key

Locate the key in Settings → API Keys
2

Click Delete

Click the delete icon next to the key
3

Confirm

Confirm the deletion

​
Monitor Key Usage

Track API key usage to detect:
  • Unusual activity patterns
  • Potential security breaches
  • Performance issues
  • Rate limit approaching
View usage data: 
Settings → API Keys → [Key Name] → Usage Stats

​
Testing Authentication

Verify your API key works: 
curl https://app.faii.ai/api/auth/verify \
  -H "Authorization: Bearer YOUR_API_KEY"
Success Response: 
{
  "success": true,
  "data": {
    "key_id": "key_abc123",
    "account_id": "acct_xyz789",
    "permissions": ["*"],
    "rate_limit": {
      "limit": 1000,
      "remaining": 995
    }
  }
}

​
Rate Limiting

API keys are subject to rate limits based on your plan:
PlanRequests/Hour
Starter100
Professional1,000
Enterprise10,000+
Rate limit info is included in all response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1634567890

​
Webhook Authentication

Webhooks use a different authentication method. See Webhooks documentation for details.

​
OAuth (Coming Soon)

OAuth 2.0 support for third-party applications is coming soon. This will allow:
  • User authorization flows
  • Granular permissions
  • Token-based access
  • Refresh token support

​
Support

Having authentication issues?

​
Next Steps

Make Your First Request

Start using the API

Campaigns API

Create and manage campaigns

Rankings API

Access ranking data

Error Handling

Handle errors gracefully