Apollo Enterprise Rbac

---
name: apollo-enterprise-rbac
description: 'Enterprise role-based access control for Apollo.io.

  Use when implementing team permissions, restricting data access,

  or setting up enterprise security controls.

  Trigger with phrases like "apollo rbac", "apollo permissions",

  "apollo roles", "apollo team access", "apollo enterprise security".

  '
allowed-tools: Read, Write, Edit, Bash(kubectl:*), Bash(curl:*)
version: 1.13.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- apollo
- security
- rbac
compatibility: Designed for Claude Code
---
# 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

```typescript
// src/rbac/roles.ts
export type Role = 'viewer' | 'analyst' | 'sales_rep' | 'sales_manager' | 'admin';

export interface Permission {
  searchPeople: boolean;       // /mixed_people/api_search (free)
  searchOrganizations: boolean; // /mixed_companies/search (free)
  enrichPerson: boolean;       // /people/match (1 credit)
  bulkEnrich: boolean;         // /people/bulk_match (credits)
  enrichOrg: boolean;          // /organizations/enrich (1 credit)
  manageContacts: boolean;     // /contacts CRUD (master key)
  manageSequences: boolean;    // /emailer_campaigns/* (master key)
  manageDeals: boolean;        // /opportunities/* (master key)
  exportPII: boolean;          // download contacts with email/phone
  viewAnalytics: boolean;      // sequence stats, usage
  manageTeam: boolean;         // create/revoke scoped keys
}

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

```typescript
// src/rbac/api-keys.ts
import crypto from 'crypto';

interface ScopedKey {
  keyHash: string;
  teamId: string;
  role: Role;
  createdBy: string;
  createdAt: string;
  expiresAt: string;
}

interface IssuedScopedKey {
  key: string; // return once; never persist or log this value
  teamId: string;
  role: Role;
  expiresAt: string;
}

// In production: store the hash in a durable database, never the raw key.
const keys = new Map<string, ScopedKey>();

function hashKey(value: string): string {
  return crypto.createHash('sha256').update(value).digest('hex');
}

export function createScopedKey(teamId: string, role: Role, createdBy: string, ttlDays: number = 90): IssuedScopedKey {
  const plaintextKey = `ak_${teamId}_${crypto.randomBytes(16).toString('hex')}`;
  const entry: ScopedKey = {
    keyHash: hashKey(plaintextKey),
    teamId, role, createdBy,
    createdAt: new Date().toISOString(),
    expiresAt: new Date(Date.now() + ttlDays * 86400000).toISOString(),
  };
  keys.set(entry.keyHash, entry);
  return { key: plaintextKey, teamId, role, expiresAt: entry.expiresAt };
}

export function resolveKey(apiKey: string): ScopedKey | null {
  const entry = keys.get(hashKey(apiKey));
  if (!entry) return null;
  if (new Date(entry.expiresAt) < new Date()) { keys.delete(entry.keyHash); return null; }
  return entry;
}

export function revokeKey(apiKey: string) { keys.delete(hashKey(apiKey)); }
```

### Step 3: Permission Middleware

```typescript
// src/rbac/middleware.ts
import { Request, Response, NextFunction } from 'express';
import { PERMISSIONS, Permission } from './roles';
import { resolveKey } from './api-keys';

// Map Apollo API paths to required permissions
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: NextFunction) => {
    const apiKey = req.headers['x-api-key'] as string;
    if (!apiKey) return res.status(401).json({ error: 'x-api-key header required' });

    const key = resolveKey(apiKey);
    if (!key) return res.status(401).json({ error: 'Invalid or expired API key' });

    if (!PERMISSIONS[key.role][action]) {
      return res.status(403).json({
        error: `Permission denied: ${action} requires role upgrade`,
        currentRole: key.role,
      });
    }

    (req as any).apolloCtx = { teamId: key.teamId, role: key.role, user: key.createdBy };
    next();
  };
}
```

### Step 4: Apollo API Proxy with RBAC

```typescript
// src/rbac/proxy.ts
import express from 'express';
import axios from 'axios';

const app = express();
app.use(express.json());

// Proxy all /apollo/* requests through RBAC
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 as any,
      url: `https://api.apollo.io/api/v1${apolloPath}`,
      data: req.body,
      params: req.query,
      headers: { 'Content-Type': 'application/json', 'x-api-key': process.env.APOLLO_API_KEY! },
    });
    res.status(response.status).json(response.data);
  } catch (err: any) {
    res.status(err.response?.status ?? 500).json(err.response?.data ?? { error: err.message });
  }
});
```

### Step 5: Admin Endpoints

```typescript
// src/rbac/admin.ts
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) => {
  // Check Apollo's usage stats
  const { data } = await axios.get('https://api.apollo.io/api/v1/usage', {
    headers: { 'x-api-key': process.env.APOLLO_API_KEY! },
  });
  res.json(data);
});

export { 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

## Examples

For a new analyst, an authorized administrator issues a time-limited
read/enrichment key for that analyst’s team, delivers the plaintext value once
through the approved secret channel, and records the key ID, role, expiry, and
approver in the audit system. The proxy stores and compares only the key hash,
so a database or log export cannot replay the credential. Test the analyst
against an allowed search endpoint and a denied sequence-write endpoint. On a
role change or suspected exposure, revoke the old key first, verify that the
proxy returns `401`, then issue a replacement; never edit the permission map
or share the Apollo master key to work around a denial.

## 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

- [Apollo API Overview](https://docs.apollo.io/docs/api-overview)
- [Create API Keys](https://docs.apollo.io/docs/create-api-key)
- [RBAC Best Practices (Auth0)](https://auth0.com/docs/manage-users/access-control/rbac)
- [View API Usage Stats](https://docs.apollo.io/reference/view-api-usage-stats)

## Next Steps

Proceed to `apollo-migration-deep-dive` for migration strategies.