EngageFabric supports multiple 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
OAuth2 Sign in with Google or GitHub for seamless onboarding
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.com/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
OAuth2 Authentication EngageFabric supports OAuth2 authentication with Google and GitHub for seamless user onboarding. This is the recommended method for signing up and logging into the admin console.
Supported Providers Provider Flow Types Best For Google Login, Signup, Link Business users with Google Workspace GitHub Login, Signup, Link Developers and technical users
Initiating OAuth Flow Redirect users to the OAuth endpoint to begin authentication:
# Redirect to Google OAuth GET https://api.engagefabric.com/api/v1/auth/oauth/google?flow=signup & redirect_uri = https://yourapp.com/callback
Flow Types Flow Description loginSign in existing user (default) signupCreate new account and tenant linkLink OAuth provider to existing account
OAuth Callback After successful authentication, users are redirected to your redirect_uri with tokens:
https://yourapp.com/callback?access_token=eyJ...&refresh_token=eyJ...&token_type=Bearer&expires_in=604800
Getting Available Providers Check which OAuth providers are enabled:
curl https://api.engagefabric.com/api/v1/auth/oauth/providers
Response: { "providers" : [ { "id" : "google" , "name" : "Google" , "enabled" : true , "authUrl" : "/api/v1/auth/oauth/google" }, { "id" : "github" , "name" : "GitHub" , "enabled" : true , "authUrl" : "/api/v1/auth/oauth/github" } ] }
OAuth is the recommended way to create an EngageFabric account. After signup, users can also set a password for email/password login.
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.com/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.com/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.com' , { 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
