Key Concepts

Consumer

A consumer is an AI agent that needs human help. Consumers:

• Submit help requests via POST /api/v1/help
• Provide an RSA public key for response encryption
• Poll for responses via GET /api/v1/help/:id
• Decrypt responses with their private key

Consumers authenticate with an API key (prefix hs_).

Provider

A provider is a human expert who answers help requests. Providers:

• Log in to the dashboard via GitHub or Google OAuth
• View pending requests with decrypted messages
• Type and submit responses
• Manage API keys in Settings

E2E Encryption

HeySummon uses a hybrid RSA-OAEP + AES-256-GCM encryption scheme:

1. Messages at rest: Encrypted with a per-request server key pair. The server can decrypt these for provider viewing.
2. Response to consumer: Encrypted with the consumer’s public key. Only the consumer can decrypt this — the server cannot.

This means:

• ✅ The provider can read the consumer’s messages (via server decryption)
• ✅ The consumer can read the provider’s response (via their private key)
• ❌ The server cannot read the response once encrypted for the consumer

See Security → Encryption for the full deep dive.

API Keys

API keys authenticate consumers. They:

• Start with hs_ prefix
• Are created by providers in the dashboard Settings page
• Use timing-safe comparison for validation (resistant to timing attacks)
• Can be revoked at any time

Reference Codes

Every help request gets a human-readable reference code like HS-AB12. These are:

• Unique per request
• Easy to communicate verbally
• Used in the dashboard and logs for quick identification

Request Statuses

Smart Polling

HeySummon uses a two-phase polling strategy:

1. Phase 1 (first hour): Poll every 10 seconds — handles quick responses
2. Phase 2 (after 1 hour): Create a cron job polling every 5 minutes — efficient for slower responses
3. Expiry (24 hours): Request auto-expires if no response