Generating API Keys

Overview

Every MCP connection starts with an API key. Keys are scoped to a single client and can optionally be restricted to specific plugins or scopes. This lets you grant precisely the right level of access — no more, no less.

Key Format

API keys use the prefix afk_ followed by a cryptographically random string:

afk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

Important: The raw key is shown exactly once at creation. After that, only the prefix (e.g., afk_a1b2...) is visible in the admin dashboard.

Creating a Key

1. Go to Admin → Clients → select a client
2. Click the API Keys tab
3. Click Generate New Key
4. Fill in:
   • Name — descriptive label (e.g., "Claude Desktop — Marketing Team")
   • Scopes — what the key can do (see below)
   • Plugins — which MCP plugins are accessible (optional; leave empty for all)
5. Click Create
6. Copy the raw key immediately — you won't see it again

Scopes

Scopes control what platform operations the key can trigger:

Default: ["outbound:call", "mcp:access"]

Plugin Restrictions

By default, a key grants access to all plugins enabled for that client. You can narrow this:

1. In the key creation form, select Restrict Plugins
2. Choose from the 14 available plugins:
   • core, ghl, ghl-social, ga4, gbp, github, google-ads, meta-ads, wordpress, twilio, sendgrid, image-generation, cloudflare, verification

Example: A marketing team key might only need ga4, meta-ads, google-ads, and gbp.

Plugin Enablement Hierarchy

Access is determined by three layers, applied in order:

1. API key plugins — if set, only these plugins are allowed
2. Agent enabledPlugins — if the key is used by a specific agent and that agent has plugins configured, those override the client-level list
3. Client enabledPlugins — the client's default plugin list
4. All plugins — if none of the above are set

Managing Existing Keys

List Keys

In Admin → Clients → API Keys, you see:

• Key prefix (e.g., afk_a1b2...)
• Name
• Scopes
• Plugin restrictions
• Active status
• Last used timestamp

Edit a Key

• Rename: Update the descriptive label anytime
• Change scopes: Add or remove permissions
• Change plugins: Narrow or expand plugin access
• Activate/deactivate: Disable without deleting

Revoke a Key

Click Revoke to permanently deactivate a key. This is instant — any connected MCP client will lose access immediately.

Security Best Practices

• One key per client/purpose: Don't reuse keys across different tools
• Principle of least privilege: Only grant the plugins and scopes actually needed
• Rotate regularly: Revoke old keys and generate new ones every 90 days
• Monitor usage: Check the Last Used timestamp. Unusual gaps may indicate a compromised key
• Never commit keys: Store them in environment variables or secure vaults, never in code repos

Troubleshooting

"Invalid or inactive API key"

• Check the key hasn't been revoked
• Verify the client status is Active (not deactivated or suspended)
• Confirm the key has the mcp:access scope

"Unknown tool" errors

• The tool's plugin may not be enabled for this client
• The API key may have plugin restrictions that exclude the needed plugin
• Check Admin → Clients → Plugins to see what's enabled

Key works for some tools but not others

• Likely a plugin restriction issue. Edit the key and verify the needed plugin is in the allowed list
• If using agent-level overrides, check the agent's enabledPlugins setting