---
sidebar_position: 3
title: Security, API Keys & Audit Logs
description: Monitor immutable workspace audit logs, enforce API key scopes, subscribe to signed webhooks, and configure iOS PushKit & Android FCM VoIP credentials.
---

# 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

| Field | Example / Values | Purpose |
| :--- | :--- | :--- |
| **Event ID** | `aud_8f3c...` | Unique immutable identifier for compliance reporting. |
| **Actor** | Workspace Member, API Key, or System | Identifies *who* performed the action—including user email/role for Console members or the exact API Key name/SID for programmatic changes. |
| **Category** | 7 security & operational domains | Groups events by operational domain for rapid filtering. |
| **Action & Outcome** | Action name • `Success` \| `Failure` | Records both completed changes and denied/failed attempts. |
| **Target Resource** | Resource type, ID, and display name | Pinpoints the exact phone number, Voice Agent, SIP trunk, recording, or member affected. |
| **Network Context** | Client IP address & User-Agent | Client IPv4/IPv6 address and browser/HTTP client signature for forensic tracing. |
| **Change Details** | Structured context metadata | Captures contextual parameters (such as purchased E.164 number, monthly fee, or updated role). |

### 2. Audit Log Event Categories

| Category | Representative Actions Tracked |
| :--- | :--- |
| **Access Control** | Inviting/removing Console members, role changes (`Owner`, `Admin`, `Viewer`), API key creation/deletion, and permission denials. |
| **Data Privacy** | Single or bulk deletion of [Call Recordings](/use-guides/call-center/call-supervision-and-recordings), [AI Call Transcriptions](/use-guides/call-center/call-logs-and-transcriptions#ai-call-transcriptions), and customer PII records. |
| **Telephony** | Purchasing or releasing DID numbers, Inbound IP ACL edits, and Outbound SIP Gateway changes. |
| **Call Center** | Creating/updating human Agent accounts, Agent Teams, Extensions, SIP Accounts, Contacts, and Audio prompts. |
| **Call Flows & AI** | Creating, publishing, modifying, or deleting visual IVR Call Flows and Voice AI Agent configurations. |
| **Billing** | Subscription plan changes, seat updates, and prepaid credit adjustments. |
| **Workspace Settings** | Workspace 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](/use-guides/administration-and-billing/billing-and-quotas#workspace-limits--quotas)**).

:::info[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:

| Scope | Allowed HTTP Methods | Recommended Use Cases |
| :--- | :--- | :--- |
| **`full`** *(Default)* | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | Backend call orchestration, dynamic Voice AI provisioning, CRM contact sync, and automated SMS dispatch. |
| **`read-only`** | `GET` 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](/developers/getting-started/authentication)** 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](/developers/webhooks/overview)** and **[Event Catalog](/developers/webhooks/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

| Parameter | iOS (`APNs PushKit VoIP`) | Android / Cross-Platform (`FCM`) |
| :--- | :--- | :--- |
| **Platform** | `ios` | `android` |
| **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 Identifier** | **Bundle 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`)<br/>• **10-char Apple Team ID** (`apns_team_id`)<br/>• **Token-based `.p8` Private Key** (`ECDSA P-256`) | **Firebase Service Account JSON** (`private_key` + `client_email` from Google Cloud / Firebase Console) |
| **Environment** | `sandbox` (Xcode debug builds) or `production` (TestFlight & App Store) | Unified production FCM delivery |

:::warning[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](/developers/sdks/flutter/voip-push)** and **[Push Credentials REST API](/developers/rest-api/workspace-api/push-credentials)**.
