This guide helps you migrate from the legacy Entitlements Agent to the new e10s-engine.
Why Migrate?
Why Migrate?
The new ReBac Engine provides:
- Fine-grained authorization with advanced relationship-based access control, with advanced features, Hierarchical authorization, listing (lookup queries), and time-based access
- Better performance with optimized queries
- Scalable architecture with Kubernetes-native deployment
| Aspect | Legacy Agent | New ReBac Engine |
|---|---|---|
| SDK Version | @frontegg/e10s-client v2.x | @frontegg/e10s-client v3.x |
| Data Sync | Polling-based bundles | Continuous sync job |
| Query Engine | OPA queries | SpiceDB queries |
| Protocol | HTTP/REST | gRPC |
| Default Port | 8181 | 50051 |
Major Version Change
Major Version Change
The migration from v2 to v3 of @frontegg/e10s-client is a major version change. Review the breaking changes and updated APIs before upgrading.
Identify how you're currently using the legacy agent:
// Legacy OPA-based implementation
import { EntitlementsClient, RequestContextType } from '@frontegg/e10s-client';
const client = new EntitlementsClient({
pdpHost: 'http://localhost:8181' // OPA endpoint
});
// Feature check
const result = await client.isEntitledTo(
{ tenantId: 'tenant-123', userId: 'user-456' },
{ type: RequestContextType.Feature, featureKey: 'premium-feature' }
);Follow the Setup Guide to deploy the new ReBac Engine alongside your existing agent.
Parallel Deployment
Parallel Deployment
Run both systems in parallel during migration to ensure zero downtime. The new engine can be deployed on different ports without affecting the legacy agent.
Update your SDK initialization to use the new SpiceDB endpoint:
// New SpiceDB-based implementation
import { EntitlementsClientFactory, RequestContextType } from '@frontegg/e10s-client';
const client = EntitlementsClientFactory.create({
engineEndpoint: 'localhost:50051', // SpiceDB gRPC endpoint
engineToken: 'your-preshared-key'
});The new ReBac engine uses entity-based subjects instead of user/tenant context for fine-grained checks:
// Before: Legacy feature check
const legacyResult = await legacyClient.isEntitledTo(
{ tenantId: 'tenant-123', userId: 'user-456' },
{ type: RequestContextType.Feature, featureKey: 'premium-feature' }
);
// After: New ReBac entity check
const newResult = await newClient.isEntitledTo(
{ entityType: 'user', key: 'user-456' },
{
type: RequestContextType.Entity,
entityType: 'document',
key: 'doc-789',
action: 'read'
}
);Backwards Compatibility
Backwards Compatibility
The new SDK still supports tenantId and userId context for feature, permission, and route checks. You only need to use entityType and key for fine-grained ReBac queries.
If you have existing authorization relationships, ensure they are configured in Frontegg:
- Define Entity Types in the Frontegg Portal or using Frontegg APIs
- Configure Relations between entity types
- Create Assignments via the Relations API
The sync job will automatically synchronize these to your SpiceDB instance.
Test both systems return consistent results:
async function validateMigration() {
// Test the same permission on both systems
const legacyResult = await legacyClient.isEntitledTo(/*...*/);
const newResult = await newClient.isEntitledTo(/*...*/);
if (legacyResult.result !== newResult.result) {
console.error('Migration validation failed!');
}
}Once validated, update your application to use the new client:
// Feature flag for gradual rollout
const USE_NEW_REBAC = process.env.USE_NEW_REBAC === 'true';
const client = USE_NEW_REBAC
? EntitlementsClientFactory.create({
spiceDBEndpoint: 'localhost:50051',
spiceDBToken: 'your-preshared-key'
})
: new EntitlementsClient({ pdpHost: 'http://localhost:8181' });After successful migration:
- Stop the legacy Entitlements Agent container
- Remove legacy environment variables
- Update documentation and runbooks
# Stop legacy agent
docker stop frontegg-entitlements-agent
docker rm frontegg-entitlements-agent| Legacy Variable | New Variable | Notes |
|---|---|---|
FRONTEGG_CLIENT_ID | FRONTEGG_CLIENT_ID | Same |
FRONTEGG_CLIENT_CREDENTIALS_OAUTH_CLIENT_ID | FRONTEGG_CLIENT_ID | Consolidated |
FRONTEGG_CLIENT_CREDENTIALS_OAUTH_SECRET | FRONTEGG_CLIENT_SECRET | Renamed |
FRONTEGG_REGION | FRONTEGG_URL | Use full URL |
POLLING_MIN_DELAY | - | Replaced by continuous sync |
POLLING_MAX_DELAY | - | Replaced by continuous sync |
| - | SPICEDB_ADDRESS | New: SpiceDB endpoint |
| - | SPICEDB_GRPC_PRESHARED_KEY | New: Auth token |
| Legacy Method | New Method | Notes |
|---|---|---|
isEntitledTo() | isEntitledTo() | Same interface, new engine |
| - | lookupTargetEntities() | New: Find accessible resources |
| - | lookupEntities() | New: Find subjects with access |
If issues occur, you can quickly rollback:
- Revert SDK initialization to use legacy client
- Restart legacy Entitlements Agent
- Update environment variables as needed
// Rollback to legacy
const client = new EntitlementsClient({
pdpHost: 'http://localhost:8181'
});- Setup Guide - Complete setup instructions
- ReBac Configuration - Define your authorization schema and relations