Authentication

Authenticate public API requests with bearer API keys.

Every public API request must include your API key as a bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The public API base URL is:

https://api.teamfollowup.ai/api

Example:

curl https://api.teamfollowup.ai/api/agent-builder/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Only send API keys over HTTPS. Do not expose API keys in browser code, mobile app bundles, client-side logs, screenshots, or support tickets.

Manage keys

Create, rotate, and revoke API keys from the API Keys page in the dashboard. Keys are shown once when created or rotated. Store the value securely before leaving the page.

The same bearer API keys authenticate the MCP action endpoint. Its advertised tool list is filtered by these scopes.

That endpoint also accepts OAuth 2.1, which is the better fit for a hosted AI assistant: the user approves the scopes in a browser instead of pasting a key into a chat. The scopes below are the same ones the consent screen grants. See MCP action tools for the flow.

Agency admins can manage keys for their own agency. Staff-only full-access keys are internal and are not part of the public API launch contract.

Scopes

API keys are scoped by module. Launch scopes are:

Scope	Allows
agents:read	List agent types, list agents, get one agent, and read outcome prompts
agents:write	Create, update, clone, and update outcome prompts
voices:read	Browse the voice catalog
calls:read	Read call history, filters, exports, call details, and execution history
calls:write	Trigger test calls and campaign tests
campaigns:read	List campaigns and campaign metadata
campaigns:write	Create, update, link, and rescan campaign resources
campaign_workflows:read	Read campaign workflow configuration
campaign_workflows:write	Save campaign workflow configuration
contacts:read	Read contacts, filters, exports, and contact call history
contacts:write	Add or remove contact kill switch status
ghl:read	Read custom fields, values, calendars, tags, pipelines, and workflows
ghl:write	Create contacts and update approved workflow settings
phone_numbers:read	List and search phone numbers
phone_numbers:write	Buy, attach, assign, unassign, and move phone numbers
phone_numbers:release	Permanently release phone numbers from the agency pool
power_dialer:read	Read pipeline, callback, and cadence data
power_dialer:write	Run, requeue, remove, and update cadence actions
projects:read	Read projects, systems, cadences, calendars, and validation results
projects:write	Create and update projects and project campaign configuration
projects:delete	Disconnect and hide projects from the customer workspace
dashboard:read	Read dashboard metrics and project filters
dashboard:write	Manage dashboard layouts and saved views
events:read	Read tenant-scoped events and event types
configuration:read	Read agency configuration
configuration:write	Update agency configuration
whitelabel:read	Read agency branding and custom-domain status
whitelabel:write	Manage agency branding, logos, and custom domains
billing:read	Read approved billing status, usage, balances, ledgers, and plans
billing:write	Manage subscriptions, top-ups, auto-recharge, and wallet configuration

For module scopes with both read and write variants, write scope also covers the same module’s read scope. For example, agents:write covers agents:read.

If a key is missing the required scope, the API returns:

{
  "success": false,
  "error": "InsufficientScope",
  "message": "This API key does not have the required scope.",
  "requiredScope": "agents:write"
}

Sensitive operations use explicit write, delete, or release scopes in addition to the existing role, tenant, ownership, billing, and resource-state checks. Internal tools and staff-only surfaces remain outside the public API.

Rate limits

API requests are rate limited by source IP. API-key-authenticated requests also use API key limits and API key plus source-IP limits. Large export endpoints can have stricter limits than normal read endpoints.

When a request is rate limited, the API returns 429:

{
  "success": false,
  "error": "TooManyRequests",
  "message": "Rate limit exceeded for this API key. Please try again later."
}