Heppu AI

Authentication

Learn how to authenticate your API requests with API keys and manage access

Authentication

The Heppu AI API uses API keys to authenticate requests. All API requests must include a valid API key to access your organization's resources.

Overview

API keys are organization-scoped credentials that grant access to your agents, calls, conversations, and other resources. Each API key is tied to a single organization and can only access data within that organization.

Security Best Practices

  • Never commit API keys to version control
  • Store keys in environment variables or secure vaults
  • Rotate keys regularly (every 90 days recommended)
  • Use different keys for development and production
  • Revoke compromised keys immediately

Creating API Keys

Via Dashboard

  1. Log in to your Heppu dashboard
  2. Navigate to Organization → API Keys
  3. Click Create API Key
  4. Enter a descriptive name (e.g., "Production Server" or "Development Key")
  5. Click Create
  6. Copy the key immediately - it will only be shown once!

API keys are shown only once during creation. If you lose a key, you'll need to create a new one and revoke the old key.

Via API

You can also create API keys programmatically using an existing key:

curl -X POST https://v2.heppu.ai/api/v1/api-keys \
  -H "x-api-key: $HEPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New API Key",
    "description": "Key for production deployment"
  }'
const response = await fetch('https://v2.heppu.ai/api/v1/api-keys', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HEPPU_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'New API Key',
    description: 'Key for production deployment'
  })
});

const data = await response.json();
console.log('API Key:', data.data.key);
// Store this key securely - it won't be shown again!
import requests
import os

response = requests.post(
    'https://v2.heppu.ai/api/v1/api-keys',
    headers={'x-api-key': os.environ.get('HEPPU_API_KEY')},
    json={
        'name': 'New API Key',
        'description': 'Key for production deployment'
    }
)

data = response.json()
print('API Key:', data['data']['key'])
# Store this key securely - it won't be shown again!

Response:

{
  "data": {
    "id": "key_abc123",
    "name": "New API Key",
    "description": "Key for production deployment",
    "key": "heppu_live_1234567890abcdefghijklmnop",
    "prefix": "heppu_live_123",
    "createdAt": "2024-12-01T12:00:00Z",
    "lastUsedAt": null
  },
  "meta": {
    "timestamp": "2024-12-01T12:00:00Z",
    "message": "API key created successfully"
  }
}

Using API Keys

The preferred method is to use the x-api-key header:

curl https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: heppu_live_1234567890abcdefghijklmnop"
const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
  headers: {
    'x-api-key': 'heppu_live_1234567890abcdefghijklmnop'
  }
});
import requests

response = requests.get(
    'https://v2.heppu.ai/api/v1/agents',
    headers={'x-api-key': 'heppu_live_1234567890abcdefghijklmnop'}
)

Header: Authorization: Bearer

Alternatively, you can use the standard Authorization header with Bearer scheme:

curl https://v2.heppu.ai/api/v1/agents \
  -H "Authorization: Bearer heppu_live_1234567890abcdefghijklmnop"
const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
  headers: {
    'Authorization': 'Bearer heppu_live_1234567890abcdefghijklmnop'
  }
});
import requests

response = requests.get(
    'https://v2.heppu.ai/api/v1/agents',
    headers={'Authorization': 'Bearer heppu_live_1234567890abcdefghijklmnop'}
)

Both authentication methods are supported. Use x-api-key for consistency with Heppu documentation, or Authorization: Bearer if your application prefers standard OAuth-style headers.

Environment Variables

Store API keys in environment variables rather than hardcoding them:

Development (.env file)

# .env
HEPPU_API_KEY=heppu_test_1234567890abcdefghijklmnop
// Load from .env file
require('dotenv').config();

const apiKey = process.env.HEPPU_API_KEY;

Production

For production environments, use your platform's secret management:

Vercel:

vercel env add HEPPU_API_KEY

AWS Lambda:

aws lambda update-function-configuration \
  --function-name my-function \
  --environment Variables={HEPPU_API_KEY=heppu_live_...}

Docker:

docker run -e HEPPU_API_KEY=heppu_live_... my-app

Kubernetes:

apiVersion: v1
kind: Secret
metadata:
  name: heppu-api-key
type: Opaque
stringData:
  api-key: heppu_live_1234567890abcdefghijklmnop

API Key Prefixes

API keys use different prefixes to indicate their environment:

  • heppu_live_* - Production keys (live environment)
  • heppu_test_* - Test keys (sandbox environment)
  • heppu_dev_* - Development keys (local development)

Test keys work only in sandbox mode and won't make real phone calls or charge your account. Use live keys for production.

Managing API Keys

List All Keys

Get all API keys for your organization:

curl https://v2.heppu.ai/api/v1/api-keys \
  -H "x-api-key: $HEPPU_API_KEY"
const response = await fetch('https://v2.heppu.ai/api/v1/api-keys', {
  headers: { 'x-api-key': process.env.HEPPU_API_KEY }
});

const data = await response.json();
console.log('API Keys:', data.data);
response = requests.get(
    'https://v2.heppu.ai/api/v1/api-keys',
    headers={'x-api-key': os.environ.get('HEPPU_API_KEY')}
)

print('API Keys:', response.json()['data'])

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production Key",
      "description": "Main production API key",
      "prefix": "heppu_live_123",
      "createdAt": "2024-11-01T10:00:00Z",
      "lastUsedAt": "2024-12-01T11:30:00Z"
    },
    {
      "id": "key_def456",
      "name": "Development Key",
      "description": "Local development",
      "prefix": "heppu_test_456",
      "createdAt": "2024-12-01T09:00:00Z",
      "lastUsedAt": null
    }
  ],
  "meta": {
    "timestamp": "2024-12-01T12:00:00Z",
    "total": 2
  }
}

For security, the full API key is never returned in list or get requests. Only the prefix is shown.

Update API Key

Update an API key's name or description:

curl -X PATCH https://v2.heppu.ai/api/v1/api-keys/key_abc123 \
  -H "x-api-key: $HEPPU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Production Key",
    "description": "Updated description"
  }'
const response = await fetch('https://v2.heppu.ai/api/v1/api-keys/key_abc123', {
  method: 'PATCH',
  headers: {
    'x-api-key': process.env.HEPPU_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Updated Production Key',
    description: 'Updated description'
  })
});
response = requests.patch(
    'https://v2.heppu.ai/api/v1/api-keys/key_abc123',
    headers={'x-api-key': os.environ.get('HEPPU_API_KEY')},
    json={
        'name': 'Updated Production Key',
        'description': 'Updated description'
    }
)

Revoke API Key

Delete an API key to immediately revoke access:

curl -X DELETE https://v2.heppu.ai/api/v1/api-keys/key_abc123 \
  -H "x-api-key: $HEPPU_API_KEY"
const response = await fetch('https://v2.heppu.ai/api/v1/api-keys/key_abc123', {
  method: 'DELETE',
  headers: { 'x-api-key': process.env.HEPPU_API_KEY }
});

console.log('Key revoked:', response.status === 204);
response = requests.delete(
    'https://v2.heppu.ai/api/v1/api-keys/key_abc123',
    headers={'x-api-key': os.environ.get('HEPPU_API_KEY')}
)

print('Key revoked:', response.status_code == 204)

Revoking an API key is immediate and cannot be undone. Any requests using that key will fail immediately.

Key Rotation

Regular key rotation is a security best practice. Here's how to rotate keys safely:

Step 1: Create a New Key

curl -X POST https://v2.heppu.ai/api/v1/api-keys \
  -H "x-api-key: $CURRENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key (New)", "description": "Rotated key"}'

Step 2: Update Your Application

Deploy your application with the new key:

# Update environment variable
export HEPPU_API_KEY=heppu_live_NEW_KEY

# Or update in your deployment platform
vercel env add HEPPU_API_KEY

Step 3: Verify the New Key Works

curl https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: $HEPPU_API_KEY"

Step 4: Revoke the Old Key

curl -X DELETE https://v2.heppu.ai/api/v1/api-keys/OLD_KEY_ID \
  -H "x-api-key: $HEPPU_API_KEY"

Rotation Schedule Recommendation

  • Production keys: Every 90 days
  • Development keys: Every 180 days
  • Immediately if compromised

Error Handling

Invalid API Key

Request:

curl https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: invalid_key"

Response (401):

{
  "error": {
    "message": "Invalid API key",
    "status": 401,
    "timestamp": "2024-12-01T12:00:00Z"
  }
}

Missing API Key

Request:

curl https://v2.heppu.ai/api/v1/agents

Response (401):

{
  "error": {
    "message": "API key required. Include x-api-key header or Authorization: Bearer header.",
    "status": 401,
    "timestamp": "2024-12-01T12:00:00Z"
  }
}

Revoked API Key

Request:

curl https://v2.heppu.ai/api/v1/agents \
  -H "x-api-key: heppu_live_revoked_key"

Response (401):

{
  "error": {
    "message": "API key has been revoked",
    "status": 401,
    "timestamp": "2024-12-01T12:00:00Z"
  }
}

Security Best Practices

DO

  • Store keys in environment variables or secret managers
  • Use different keys for development, staging, and production
  • Rotate keys every 90 days
  • Monitor key usage via the dashboard
  • Revoke compromised keys immediately
  • Use HTTPS for all API requests (enforced)
  • Implement rate limiting in your application

DON'T

  • Commit keys to Git repositories
  • Share keys via email or chat
  • Use production keys in development
  • Store keys in client-side code
  • Log API keys in application logs
  • Use the same key across multiple projects
  • Ignore unusual activity alerts

Monitoring Key Usage

Track API key usage in your dashboard:

  1. Navigate to Organization → API Keys
  2. Click on a key to view:
    • Last used timestamp
    • Request count (last 30 days)
    • Recent requests
    • Geographic usage patterns

Set up alerts for unusual API key activity in your organization settings.

Organization Scoping

All API keys are scoped to a single organization. If you're a member of multiple organizations:

  1. Each organization has its own set of API keys
  2. Keys from one organization cannot access another organization's data
  3. Switch organizations in the dashboard to manage different key sets

Testing Authentication

Here's a simple script to test your API key setup:

const fetch = require('node-fetch');

async function testAuth() {
  const apiKey = process.env.HEPPU_API_KEY;

  if (!apiKey) {
    console.error('❌ HEPPU_API_KEY not set');
    return;
  }

  try {
    const response = await fetch('https://v2.heppu.ai/api/v1/agents', {
      headers: { 'x-api-key': apiKey }
    });

    if (response.ok) {
      console.log('✅ Authentication successful');
      const data = await response.json();
      console.log(`   Organization has ${data.data.length} agents`);
    } else {
      console.error(`❌ Authentication failed: ${response.status}`);
      const error = await response.json();
      console.error(`   ${error.error.message}`);
    }
  } catch (error) {
    console.error('❌ Network error:', error.message);
  }
}

testAuth();

Run it:

node test-auth.js

Next Steps

Quick Start

Create your first agent with authenticated API requests

Error Handling

Learn how to handle authentication errors properly

Rate Limits

Understand API rate limits and quotas

Webhooks

Set up secure webhook endpoints

Need Help?

Having trouble with authentication?

  • Check the troubleshooting section in the Quick Start guide
  • Review authentication errors in your dashboard logs
  • Contact support at support@heppu.ai with your organization ID (never share your API key)

API Overview

Introduction to the Heppu AI API for building voice and chat AI agents

Error Handling

Complete reference for API error codes, formats, and handling strategies

On this page

AuthenticationOverviewCreating API KeysVia DashboardVia APIUsing API KeysHeader: x-api-key (Recommended)Header: Authorization: BearerEnvironment VariablesDevelopment (.env file)ProductionAPI Key PrefixesManaging API KeysList All KeysUpdate API KeyRevoke API KeyKey RotationStep 1: Create a New KeyStep 2: Update Your ApplicationStep 3: Verify the New Key WorksStep 4: Revoke the Old KeyError HandlingInvalid API KeyMissing API KeyRevoked API KeySecurity Best PracticesDODON'TMonitoring Key UsageOrganization ScopingTesting AuthenticationNext StepsNeed Help?