Apollo Enterprise RBAC
Overview
Role-based access control for Apollo.io API integrations. Apollo API keys are all-or-nothing (standard vs master), so RBAC must be implemented in your application layer as a proxy between users and the Apollo API. This skill builds a permission matrix, scoped API key system, Express middleware, and admin audit endpoints.
Prerequisites
- Apollo master API key
- Node.js 18+ with Express
Instructions
Step 1: Define Roles and Permission Matrix
Map Apollo API operations to team roles. Apollo's API has two main categories:
- Read-only: search (free), enrichment (credits)
- Write: contacts CRUD, sequences, deals, tasks
export type Role = 'viewer' | 'analyst' | 'sales_rep' | 'sales_manager' | 'admin';
export interface Permission {
searchPeople: boolean;
searchOrganizations: boolean;
enrichPerson: boolean;
bulkEnrich: boolean;
enrichOrg: boolean;
manageContacts: boolean;
manageSequences: boolean;
manageDeals: boolean;
exportPII: boolean;
viewAnalytics: boolean;
manageTeam: boolean;
}
export const PERMISSIONS: Record<Role, Permission> = {
viewer: {
searchPeople: true, searchOrganizations: true, enrichPerson: false,
bulkEnrich: false, enrichOrg: false, manageContacts: false,
manageSequences: false, manageDeals: false, exportPII: false,
viewAnalytics: true, manageTeam: false,
},
analyst: {
searchPeople: true, searchOrganizations: true, enrichPerson: true,
bulkEnrich: false, enrichOrg: true, manageContacts: false,
manageSequences: false, manageDeals: false, exportPII: false,
viewAnalytics: true, manageTeam: false,
},
sales_rep: {
searchPeople: true, searchOrganizations: true, enrichPerson: true,
bulkEnrich: false, enrichOrg: true, manageContacts: true,
manageSequences: true, manageDeals: true, exportPII: false,
viewAnalytics: false, manageTeam: false,
},
sales_manager: {
searchPeople: true, searchOrganizations: true, enrichPerson: true,
bulkEnrich: true, enrichOrg: true, manageContacts: true,
manageSequences: true, manageDeals: true, exportPII: true,
viewAnalytics: true, manageTeam: true,
},
admin: {
searchPeople: true, searchOrganizations: true, enrichPerson: true,
bulkEnrich: true, enrichOrg: true, manageContacts: true,
manageSequences: true, manageDeals: true, exportPII: true,
viewAnalytics: true, manageTeam: true,
},
};
Step 2: Scoped API Key System
import crypto from 'crypto';
interface ScopedKey {
key: string;
teamId: string;
role: Role;
createdBy: string;
createdAt: string;
expiresAt: string;
}
const keys = new Map<string, ScopedKey>();
export function createScopedKey(teamId: string, role: Role, createdBy: string, ttlDays: number = 90): ScopedKey {
const entry: ScopedKey = {
key: `ak_${teamId}_${crypto.randomBytes(16).toString('hex')}`,
teamId, role, createdBy,
createdAt: new Date().toISOString(),
expiresAt: new Date(.() + ttlDays * ).(),
};
keys.(entry., entry);
entry;
}
(): | {
entry = keys.(apiKey);
(!entry) ;
( (entry.) < ()) { keys.(apiKey); ; }
entry;
}
() { keys.(apiKey); }
Step 3: Permission Middleware
import { Request, Response, NextFunction } from 'express';
import { PERMISSIONS, Permission } from './roles';
import { resolveKey } from './api-keys';
const ENDPOINT_PERMISSIONS: Record<string, keyof Permission> = {
'/mixed_people/api_search': 'searchPeople',
'/mixed_companies/search': 'searchOrganizations',
'/people/match': 'enrichPerson',
'/people/bulk_match': 'bulkEnrich',
'/organizations/enrich': 'enrichOrg',
'/contacts': 'manageContacts',
'/emailer_campaigns': 'manageSequences',
'/opportunities': 'manageDeals',
};
export function requirePermission(action: keyof Permission) {
return (req: Request, res: Response, next: ) => {
apiKey = req.[] ;
(!apiKey) res.().({ : });
key = (apiKey);
(!key) res.().({ : });
(![key.][action]) {
res.().({
: ,
: key.,
});
}
(req ). = { : key., : key., : key. };
();
};
}
Step 4: Apollo API Proxy with RBAC
import express from 'express';
import axios from 'axios';
const app = express();
app.use(express.json());
app.all('/apollo/*', (req, res, next) => {
const apolloPath = req.path.replace('/apollo', '');
const matchedKey = Object.keys(ENDPOINT_PERMISSIONS).find((p) => apolloPath.startsWith(p));
if (!matchedKey) return res.status(404).json({ error: 'Unknown Apollo endpoint' });
requirePermission(ENDPOINT_PERMISSIONS[matchedKey])(req, res, next);
}, async (req, res) => {
const apolloPath = req.path.replace('/apollo', '');
try {
const response = await axios({
method: req.method ,
: ,
: req.,
: req.,
: { : , : process..! },
});
res.(response.).(response.);
} (: ) {
res.(err.?. ?? ).(err.?. ?? { : err. });
}
});
Step 5: Admin Endpoints
import { Router } from 'express';
import { requirePermission } from './middleware';
import { createScopedKey, revokeKey } from './api-keys';
const admin = Router();
admin.use(requirePermission('manageTeam'));
admin.post('/keys', (req, res) => {
const { teamId, role, ttlDays } = req.body;
const ctx = (req as any).apolloCtx;
const key = createScopedKey(teamId, role, ctx.user, ttlDays);
res.json({ key: key.key, role: key.role, expiresAt: key.expiresAt });
});
admin.delete('/keys/:key', (req, res) => {
revokeKey(req.params.key);
res.json({ revoked: true });
});
admin.get('/usage', async (req, res) => {
{ data } = axios.(, {
: { : process..! },
});
res.(data);
});
{ admin };
Output
- Five-tier role system mapping to Apollo API operations
- Scoped API key creation with configurable TTL and revocation
- Express middleware enforcing per-endpoint permissions
- Apollo API proxy routing all requests through RBAC
- Admin endpoints for key management and usage stats
Error Handling
| Issue | Resolution |
|---|
| 403 Permission denied | Check role matrix; request upgrade from admin |
| Key expired | Admin creates new key via POST /keys |
| Wrong role for bulk enrichment | Only sales_manager and admin have bulkEnrich |
| Proxy timeout | Increase timeout, check Apollo API latency |
Resources
Next Steps
Proceed to apollo-migration-deep-dive for migration strategies.
