---

name: instantly-enterprise-rbac description: | Configure Instantly enterprise SSO, role-based access control, and organization management. Use when implementing SSO integration, configuring role-based permissions, or setting up organization-level controls for Instantly. Trigger with phrases like "instantly SSO", "instantly RBAC", "instantly enterprise", "instantly roles", "instantly permissions", "instantly SAML". allowed-tools: Read, Write, Edit version: 1.0.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io

Instantly Enterprise RBAC

Overview

Configure enterprise-grade access control for Instantly integrations.

Prerequisites

• Instantly Enterprise tier subscription
• Identity Provider (IdP) with SAML/OIDC support
• Understanding of role-based access patterns
• Audit logging infrastructure

Role Definitions

| Role | Permissions | Use Case | |------|-------------|----------| | Admin | Full access | Platform administrators | | Developer | Read/write, no delete | Active development | | Viewer | Read-only | Stakeholders, auditors | | Service | API access only | Automated systems |

Role Implementation

enum InstantlyRole {
  Admin = 'admin',
  Developer = 'developer',
  Viewer = 'viewer',
  Service = 'service',
}

interface InstantlyPermissions {
  read: boolean;
  write: boolean;
  delete: boolean;
  admin: boolean;
}

const ROLE_PERMISSIONS: Record<InstantlyRole, InstantlyPermissions> = {
  admin: { read: true, write: true, delete: true, admin: true },
  developer: { read: true, write: true, delete: false, admin: false },
  viewer: { read: true, write: false, delete: false, admin: false },
  service: { read: true, write: true, delete: false, admin: false },
};

function checkPermission(
  role: InstantlyRole,
  action: keyof InstantlyPermissions
): boolean {
  return ROLE_PERMISSIONS[role][action];
}

SSO Integration

SAML Configuration

// Instantly SAML setup
const samlConfig = {
  entryPoint: 'https://idp.company.com/saml/sso',
  issuer: 'https://instantly.com/saml/metadata',
  cert: process.env.SAML_CERT,
  callbackUrl: 'https://app.yourcompany.com/auth/instantly/callback',
};

// Map IdP groups to Instantly roles
const groupRoleMapping: Record<string, InstantlyRole> = {
  'Engineering': InstantlyRole.Developer,
  'Platform-Admins': InstantlyRole.Admin,
  'Data-Team': InstantlyRole.Viewer,
};

OAuth2/OIDC Integration

import { OAuth2Client } from '@instantly/sdk';

const oauthClient = new OAuth2Client({
  clientId: process.env.INSTANTLY_OAUTH_CLIENT_ID!,
  clientSecret: process.env.INSTANTLY_OAUTH_CLIENT_SECRET!,
  redirectUri: 'https://app.yourcompany.com/auth/instantly/callback',
  scopes: ['read', 'write'],
});

Organization Management

interface InstantlyOrganization {
  id: string;
  name: string;
  ssoEnabled: boolean;
  enforceSso: boolean;
  allowedDomains: string[];
  defaultRole: InstantlyRole;
}

async function createOrganization(
  config: InstantlyOrganization
): Promise<void> {
  await instantlyClient.organizations.create({
    ...config,
    settings: {
      sso: {
        enabled: config.ssoEnabled,
        enforced: config.enforceSso,
        domains: config.allowedDomains,
      },
    },
  });
}

Access Control Middleware

function requireInstantlyPermission(
  requiredPermission: keyof InstantlyPermissions
) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const user = req.user as { instantlyRole: InstantlyRole };

    if (!checkPermission(user.instantlyRole, requiredPermission)) {
      return res.status(403).json({
        error: 'Forbidden',
        message: `Missing permission: ${requiredPermission}`,
      });
    }

    next();
  };
}

// Usage
app.delete('/instantly/resource/:id',
  requireInstantlyPermission('delete'),
  deleteResourceHandler
);

Audit Trail

interface InstantlyAuditEntry {
  timestamp: Date;
  userId: string;
  role: InstantlyRole;
  action: string;
  resource: string;
  success: boolean;
  ipAddress: string;
}

async function logInstantlyAccess(entry: InstantlyAuditEntry): Promise<void> {
  await auditDb.insert(entry);

  // Alert on suspicious activity
  if (entry.action === 'delete' && !entry.success) {
    await alertOnSuspiciousActivity(entry);
  }
}

Instructions

Step 1: Define Roles

Map organizational roles to Instantly permissions.

Step 2: Configure SSO

Set up SAML or OIDC integration with your IdP.

Step 3: Implement Middleware

Add permission checks to API endpoints.

Step 4: Enable Audit Logging

Track all access for compliance.

Output

• Role definitions implemented
• SSO integration configured
• Permission middleware active
• Audit trail enabled

Error Handling

| Issue | Cause | Solution | |-------|-------|----------| | SSO login fails | Wrong callback URL | Verify IdP config | | Permission denied | Missing role mapping | Update group mappings | | Token expired | Short TTL | Refresh token logic | | Audit gaps | Async logging failed | Check log pipeline |

Examples

Quick Permission Check

if (!checkPermission(user.role, 'write')) {
  throw new ForbiddenError('Write permission required');
}

Resources

• Instantly Enterprise Guide
• SAML 2.0 Specification
• OpenID Connect Spec

Next Steps

For major migrations, see instantly-migration-deep-dive.