Skip to main content
LLM ReadyRaw Markdown for AI agents:security-and-audit-logs.mdFull index:llms.txtllms-full.txt

Security, API Keys & Audit Logs

Firetell provides defense-in-depth security controls, immutable administrative telemetry, and scoped credentials for server-to-server and mobile VoIP integrations.


Workspace Audit Logs​

Open Console → Settings → Audit Logs to inspect a real-time, append-only record of administrative, configuration, and data-privacy actions across your workspace (aud_...).

1. What Every Audit Log Entry Records​

FieldExample / ValuesPurpose
Event IDaud_8f3c...Unique immutable identifier for compliance reporting.
ActorWorkspace Member, API Key, or SystemIdentifies who performed the action—including user email/role for Console members or the exact API Key name/SID for programmatic changes.
Category7 security & operational domainsGroups events by operational domain for rapid filtering.
Action & OutcomeAction name • Success | FailureRecords both completed changes and denied/failed attempts.
Target ResourceResource type, ID, and display namePinpoints the exact phone number, Voice Agent, SIP trunk, recording, or member affected.
Network ContextClient IP address & User-AgentClient IPv4/IPv6 address and browser/HTTP client signature for forensic tracing.
Change DetailsStructured context metadataCaptures contextual parameters (such as purchased E.164 number, monthly fee, or updated role).

2. Audit Log Event Categories​

CategoryRepresentative Actions Tracked
Access ControlInviting/removing Console members, role changes (Owner, Admin, Viewer), API key creation/deletion, and permission denials.
Data PrivacySingle or bulk deletion of Call Recordings, AI Call Transcriptions, and customer PII records.
TelephonyPurchasing or releasing DID numbers, Inbound IP ACL edits, and Outbound SIP Gateway changes.
Call CenterCreating/updating human Agent accounts, Agent Teams, Extensions, SIP Accounts, Contacts, and Audio prompts.
Call Flows & AICreating, publishing, modifying, or deleting visual IVR Call Flows and Voice AI Agent configurations.
BillingSubscription plan changes, seat updates, and prepaid credit adjustments.
Workspace SettingsWorkspace profile/timezone updates, webhook endpoint modifications, and mobile Push Credential changes.

Log retention automatically follows your subscription plan's Audit Log Retention entitlement (viewable under Workspace Limits & Quotas).

Two-Factor Authentication (2FA) Enforcement

High-impact actions—such as purchasing phone numbers, altering carrier SIP trunk gateways, or managing security credentials—enforce account-level Two-Factor Authentication (2FA) to protect your telecom infrastructure even if a session is left unattended.


Workspace API Keys & Scopes​

Navigate to Console → Settings → API Keys to issue credentials (SID + Secret) for backend services, CI/CD pipelines, and analytics dashboards.

Principle of Least Privilege (scopes)​

When clicking Create API Key, choose the minimum scope required for that integration:

ScopeAllowed HTTP MethodsRecommended Use Cases
full (Default)GET, POST, PUT, PATCH, DELETEBackend call orchestration, dynamic Voice AI provisioning, CRM contact sync, and automated SMS dispatch.
read-onlyGET only (403 Forbidden on write/delete)BI/analytics pipelines pulling CDRs, QA dashboards, external monitoring, and billing reconciliation scripts.

API Key Security Hygiene​

  • Never embed Workspace API Keys in browser JS or mobile app binaries: Use Workspace API Keys strictly on trusted backend servers. For browser WebRTC or Flutter mobile apps, mint short-lived user/client tokens via the Client/Agent Auth endpoints.
  • Per-Integration Keys & Zero-Downtime Rotation: Issue separate keys per service (e.g., HubSpot Sync Prod, Datadog CDR Poller). To rotate a key without downtime, create a new key, deploy the updated secret to your server, verify traffic in Audit Logs, and delete the old key.
  • See the Developer Authentication Guide for full header syntax.

Event Webhooks​

Open Console → Settings → Webhooks to push real-time JSON event notifications from Firetell to your HTTPS backend—eliminating polling loops.

Supported Event Families (18 Events)​

  • Voice Call Lifecycle: call.created, call.answered, call.ended
  • Post-Call Media & AI Intelligence: call.recording.ready, call.transcription.completed, call.transcription.summary
  • SMS & MMS Messaging: message.received, message.sent, message.delivered, message.failed, message.undelivered
  • CRM & Directory Sync: contact.created, contact.updated, contact.deleted, agent.created, agent.updated, agent.deleted
  • Billing Telemetry: workspace.credit.updated

Endpoint Security​

  • Every webhook endpoint automatically generates a unique 64-character cryptographic signing secret so your server can verify payload authenticity and reject spoofed requests.
  • You can also attach custom HTTP Headers (e.g., X-Internal-Token) and enable or pause an endpoint at any time during maintenance windows.
  • Read payload schemas and signature verification code examples in Webhooks Overview and Event Catalog.

Mobile VoIP Push Credentials (APNs & FCM)​

Modern iOS and Android operating systems suspend background TCP/WebSocket connections aggressively to save battery. To wake up your custom mobile app instantaneously and display the native incoming call screen (Apple CallKit on iOS / ConnectionService on Android), configure your push credentials under Console → Settings → Push Credentials.

iOS vs. Android Credential Parameters​

ParameteriOS (APNs PushKit VoIP)Android / Cross-Platform (FCM)
Platformiosandroid
Bound API Key (api_key_sid)Associates the push certificate with the specific Workspace API Key SID minting mobile client tokens.Associates the FCM configuration with the specific Workspace API Key SID.
App IdentifierBundle ID (apns_bundle_id, e.g., com.yourcompany.softphone)Package Name (fcm_package_name, e.g., com.yourcompany.softphone)
Credential Material (Encrypted at Rest)• 10-char Apple Key ID (apns_key_id)
• 10-char Apple Team ID (apns_team_id)
• Token-based .p8 Private Key (ECDSA P-256)
Firebase Service Account JSON (private_key + client_email from Google Cloud / Firebase Console)
Environmentsandbox (Xcode debug builds) or production (TestFlight & App Store)Unified production FCM delivery
Sandbox vs. Production APNs Mismatch

Apple maintains separate PushKit gateways for sandbox (direct Xcode USB/wireless debug builds) and production (TestFlight and App Store builds). If incoming calls ring in Xcode debug builds but fail silently on TestFlight, create a second Push Credential with apns_environment set to production.

For end-to-end mobile integration code, follow the Flutter VoIP Push & CallKit Guide and Push Credentials REST API.