Authentication

API Keys

API keys are used for server-to-server integrations such as scripts, webhooks, and custom applications that call Heard’s API programmatically.

Creating an API Key

1. Navigate to Settings → Developer → API Keys
2. Click Create Key
3. Give it a name (e.g., “Production Webhook” or “Zapier Integration”)
4. Select the scopes:

Scope	Grants Access To
ingest	Submit audio and transcripts for processing
analyze	Analyze transcripts, retrieve analysis results
customer-context	Query customer data, dossiers, and conversation history

5. Click Create and copy the key immediately, as it is only shown once.

Using an API Key

Include the key in the X-API-Key header:

curl -X POST https://api.heard.ai/v1/ingest/audio \
  -H "X-API-Key: sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://storage.example.com/call.wav"}'

Key Management

• Keys can be revoked at any time in Settings → Developer → API Keys
• Each key shows its last used date and scope
• Create separate keys for different integrations so you can revoke one without breaking others.

---

OAuth (User Sessions)

The Web Dashboard, Google Workspace Add-ons, and OpenClaw use Google OAuth 2.0 for user authentication. This is handled automatically and requires no developer setup.

If you’re building a custom frontend that needs user-level access:

1. Redirect the user to Heard’s OAuth flow
2. Receive a JWT access token (1-hour expiry) and refresh token (30-day expiry)
3. Include the JWT in the Authorization header:

curl https://api.heard.ai/v1/triage \
  -H "Authorization: Bearer eyJhbGci..."