Node.js SDK

Express/Fastify middleware for JWT verification, permission checking, and cloud credentials.

Install

npm install authfi

Initialize

const authfi = require('authfi')({
  tenant: 'acme',
  apiKey: 'sk_live_...',            // Management API key
  applicationId: 'your-client-id',  // Your app's client_id
  baseUrl: 'https://api.authfi.app', // Optional, defaults to this
  autoSync: true                     // Auto-sync permissions on start
});

Middleware

require(permission)

Verify JWT + check that user has the specified permission:

app.get('/api/users', authfi.require('read:users'), (req, res) => {
  // req.user = { id, email, roles, permissions, groups, tenant_id, org_id }
  res.json(req.user);
});

requireRole(role)

Verify JWT + check that user has the specified role:

app.post('/api/admin', authfi.requireRole('admin'), handler);

authenticate()

Just verify the JWT without any permission check:

app.get('/api/profile', authfi.authenticate(), (req, res) => {
  res.json(req.user);
});

Permission Auto-Sync

Register permissions in code. On start(), they sync to AuthFI so admins can assign them to roles.

authfi.registerPermission('read:users', 'List all users');
authfi.registerPermission('write:users', 'Create and update users');
authfi.registerPermission('delete:users', 'Delete users');
authfi.registerPermission('read:orders', 'View orders');

// Call start to sync
await authfi.start();

Or use the bulk sync:

await authfi.syncPermissions([
  { name: 'read:users', description: 'List all users' },
  { name: 'write:users', description: 'Create and update users' }
]);

Token Verification

Manual verification (without middleware):

const claims = await authfi.verifyToken(tokenString);
// claims = { sub, email, roles, permissions, groups, tenant_id, ... }

JWKS is cached for 5 minutes by default.

Cloud Credentials

Get cloud credentials for the authenticated user:

// Get AWS credentials
const creds = await authfi.cloud.credentials(req.user.token, 'aws', {
  roleArn: 'arn:aws:iam::123:role/MyRole'
});
// creds = { access_key_id, secret_access_key, session_token, expiration }

// Get GCP token
const gcpCreds = await authfi.cloud.credentials(req.user.token, 'gcp', {
  project: 'my-project'
});

// Get raw OIDC token for custom federation
const oidcToken = await authfi.cloud.token(req.user.token, 'custom-audience', 900);

Error Handling

app.get('/api/data', authfi.require('read:data'), handler);

// If JWT is missing/invalid: 401 { error: "unauthorized" }
// If permission missing: 403 { error: "forbidden", required: "read:data" }

Configuration

Option	Default	Description
tenant	required	Tenant slug
apiKey	required	Management API key
applicationId	—	App client_id (for cloud credentials)
baseUrl	https://api.authfi.app	API base URL
autoSync	false	Sync permissions on start()
jwksCacheTTL	300	JWKS cache TTL in seconds