Key Concepts

Understanding these core concepts will help you build better integrations with CHeKT.

The Gateway Model

What is a Gateway?

CHeKT acts as a gateway or bridge between security systems and monitoring centers. Instead of integrating with each monitoring center individually, you integrate once with CHeKT.

Without CHeKT:
Your System → Monitoring Center A ❌
Your System → Monitoring Center B ❌  (Multiple integrations)
Your System → Monitoring Center C ❌

With CHeKT:
Your System → CHeKT Gateway → Any Monitoring Center ✓ (One integration)

Benefits of the Gateway Model

• Single Integration Point - Connect once, reach all monitoring centers
• Protocol Translation - CHeKT handles different monitoring protocols
• Enrichment - Add video verification automatically
• Reliability - Built-in redundancy and failover

Core Entities

Sites

A site represents a physical location being monitored (home, business, warehouse, etc.).

Key Properties:

• Address - Physical location
• Timezone - For scheduling and timestamps
• Monitoring Status - Whether monitoring is active
• Emergency Contacts - Who to notify in emergencies

Example:

{
  "id": "site_abc123",
  "name": "John's Home",
  "address": "123 Main St, San Francisco, CA",
  "monitoring_enabled": true
}

Devices (Cameras, Sensors, Panels)

Devices are the physical hardware at a site that detect events and capture video.

Types of Devices:

• Cameras - Capture video, detect motion
• Sensors - Door/window sensors, motion detectors
• Panels - Control panels, alarm systems

Key Properties:

• Device ID - Unique identifier from your system
• Capabilities - What the device can do (record, PTZ, audio)
• Status - Online/offline state
• Stream URLs - Where to access live video

Example:

{
  "id": "cam_xyz789",
  "name": "Front Door Camera",
  "device_id": "camera_001",
  "type": "camera",
  "capabilities": {
    "record": true,
    "motion_detection": true,
    "two_way_audio": true,
    "ptz": false
  }
}

Events (Alarms, Troubles, Status Changes)

Events are occurrences that need to be reported to monitoring centers.

Event Types:

Key Properties:

• Event Time - When it occurred (ISO 8601 format)
• Event Type - Alarm, trouble, or arming
• Device ID - Which device triggered it
• Video Clips - Associated video for verification

Example Alarm Event:

{
  "event_id": "evt_abc123",
  "event_type": "alarm",
  "event_subtype": "intrusion",
  "event_time": "2026-02-11T14:30:00Z",
  "site_id": "site_abc123",
  "camera_id": "cam_xyz789",
  "video_clips": [
    {
      "start_time": "2026-02-11T14:29:55Z",
      "duration": 10,
      "url": "https://..."
    }
  ]
}

Video Verification

Why Video Matters

Video verification dramatically improves alarm response:

• 80% reduction in false alarms
• 3x faster police dispatch for real threats
• Better evidence for insurance and prosecution
• Higher customer satisfaction

How It Works

1. Event Occurs - Camera detects motion/alarm
2. Video Captured - System records pre/post event video
3. Attached to Event - Video URL included in alarm event
4. Delivered Together - Monitoring center receives alarm + video simultaneously
5. Operator Reviews - Human verification before dispatch

Video Requirements

• Format: MP4, H.264 codec
• Duration: 5-30 seconds (configurable)
• Resolution: Minimum 720p recommended
• Pre-Alarm: Include 5 seconds before event
• Post-Alarm: Include 5-10 seconds after event

Arming States

What is Arming?

Arming refers to the security system's armed/disarmed state. Different arming modes control which devices are active.

Arming Modes

Arming Schedules

Automate arming based on time:

{
  "schedule": {
    "monday": {
      "arm_time": "08:00",
      "arm_mode": "away",
      "disarm_time": "18:00"
    },
    "tuesday": {
      "arm_time": "08:00",
      "arm_mode": "away",
      "disarm_time": "18:00"
    }
  }
}

Two-Way Communication

Bidirectional Flow

CHeKT enables two-way communication between monitoring centers and security systems:

Outbound (You → Monitoring):

• Alarm events
• Status updates
• Video verification
• Device health

Inbound (Monitoring → You):

• Arming commands
• Camera control requests
• Audio communication requests
• Verification status

Webhooks

Webhooks deliver real-time notifications from CHeKT to your system:

Event occurs at monitoring center
         ↓
CHeKT sends webhook to your endpoint
         ↓
Your system receives and processes

Common Webhook Events:

• arming.command - Arm/disarm request
• camera.view_request - Live view requested
• verification.complete - Alarm verified
• device.status_change - Device online/offline

Authentication

Public API: API Keys

Simple Bearer Token authentication:

Authorization: Bearer YOUR_API_KEY

• Permanent until manually rotated
• Scoped to your dealer account
• Easy to use for testing and development

Partner API: OAuth 2.0 + JWT

Two-stage authentication:

1. OAuth Authorization Code Flow (for dealer connection)

User → Authorizes → OAuth Flow → Dealer Connected

2. M2M with JWT (for API calls)

Generate JWT → Sign with Secret → Exchange for Token → API Call

• Secure using RS256 signing
• Short-lived tokens (1 hour expiry)
• Cached for performance

Rate Limiting

CHeKT implements rate limiting to ensure fair usage and system stability.

Limits

Best Practices

• Cache responses when appropriate
• Use bulk endpoints for multiple operations
• Implement retry logic with exponential backoff
• Monitor rate limit headers in responses

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1644595200

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "ValidationError",
  "message": "Missing required field: site_id",
  "details": {
    "field": "site_id",
    "required": true
  }
}

Retry Strategy

Implement exponential backoff for failed requests:

1st retry: Wait 1 second
2nd retry: Wait 2 seconds
3rd retry: Wait 4 seconds
4th retry: Wait 8 seconds
Max retries: 5

Idempotency

What is Idempotency?

Idempotent operations produce the same result when called multiple times. This is crucial for handling network failures and retries.

Idempotency Keys

Some endpoints support idempotency keys to prevent duplicate operations:

POST /ext/v1/events
Idempotency-Key: unique-request-id-12345

If you retry with the same key, CHeKT returns the original response instead of creating a duplicate.

Environments

Development (Sandbox)

Base URL: https://api.chektdev.com

• Purpose: Testing and development
• Data: Isolated from production
• Monitoring: No real monitoring centers
• Rate Limits: Lower limits

Production

Base URL: https://api.chekt.com

• Purpose: Live customer operations
• Data: Real customer data
• Monitoring: Connected to real monitoring centers
• Rate Limits: Full production limits

Best Practices Summary

Next Steps

Now that you understand the key concepts, start building: