EngageFabric supports two authentication methods depending on your use case:
API Keys For server-to-server communication and backend integrations
JWT Tokens For admin console access and user authentication
API Key Authentication API keys are the recommended way to authenticate your application with EngageFabric. They are project-specific and should be kept secure on your server.
Getting Your API Key
Log in to the Admin Console
Navigate to your project
Go to Settings > API Keys
Copy your API key
Using API Keys Include your API key in the X-API-Key header:
curl -X GET "https://api.engagefabric.cloud/api/v1/players" \ -H "X-API-Key: your-api-key"
API Key Types Type Prefix Use Case Live ef_live_Production environment Test ef_test_Development and testing
Security Best Practices:
Never expose API keys in client-side code
Rotate keys regularly
Use environment variables to store keys
Use test keys for development
JWT Authentication JWT (JSON Web Tokens) are used for authenticating admin console users and can be used for WebSocket connections.
Obtaining a JWT Token curl -X POST "https://api.engagefabric.cloud/api/v1/auth/login" \ -H "Content-Type: application/json" \ -d '{ "email": "admin@example.com", "password": "your-password" }' Response: { "accessToken" : "eyJhbGciOiJIUzI1NiIs..." , "user" : { "id" : "user-uuid" , "email" : "admin@example.com" , "role" : "OWNER" } } Using JWT Tokens Include the token in the Authorization header:
curl -X GET "https://api.engagefabric.cloud/api/v1/tenants" \ -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." Token Expiration Token Type Expiration Use Case Access Token 7 days API requests WebSocket Token 15 minutes Real-time connections
WebSocket Authentication For real-time features, authenticate WebSocket connections with a short-lived JWT:
import { io } from 'socket.io-client' ; const socket = io ( 'wss://api.engagefabric.cloud' , { auth: { token: 'your-websocket-jwt' } }); socket . on ( 'connect' , () => { console . log ( 'Connected to EngageFabric WebSocket' ); }); WebSocket tokens have a shorter expiration (15 minutes) for security.
Implement token refresh logic in your application.
Role-Based Access Control (RBAC) EngageFabric implements RBAC for tenant management:
Role Permissions Owner Full access, can delete tenant Admin Manage projects, users, and settings Designer Create and edit rules, quests, adventures Developer Read access, API key management Viewer Read-only access to dashboards
Rate Limits API requests are rate-limited based on your project tier:
Tier Rate Limit Free 100 requests/minute Starter 500 requests/minute Pro 1,000 requests/minute Enterprise Custom limits
When rate limited, you’ll receive a 429 Too Many Requests response with headers:
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1699900000 Implement exponential backoff when you receive rate limit errors.
Error Responses Authentication errors return standard error responses:
{ "error" : { "code" : "UNAUTHORIZED" , "message" : "Invalid or expired API key" , "requestId" : "req-abc123" , "timestamp" : "2025-01-21T10:00:00Z" } } Error Code HTTP Status Description UNAUTHORIZED401 Missing or invalid credentials FORBIDDEN403 Insufficient permissions RATE_LIMITED429 Too many requests
