Authentication

The IdentityCall API uses API keys to authenticate requests. This guide covers how to create, manage, and use API keys securely.

How API Keys Work

API keys are long-lived credentials that identify your application when making API requests. Each key:

• Is tied to a specific account
• Has configurable permissions (read, write, delete)
• Can be scoped to a specific project
• Tracks usage for auditing
• Can be revoked at any time

Creating an API Key

Via the Dashboard

1. Log in to the IdentityCall Dashboard 
2. Navigate to Settings → API Keys
3. Click Create New API Key
4. Configure the key:
   • Name: A descriptive name (e.g., “Production Backend”, “Analytics Service”)
   • Permissions: Select which operations the key can perform
   • Project Scope: Optionally limit the key to a specific project
   • Expiration: Set an expiry date (optional)
5. Click Create Key

API Key Format

API keys follow this format:

idc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: idc_ (identifies it as an IdentityCall key)
• Random: 32 alphanumeric characters

Using Your API Key

Include your API key in the Authorization header with the Bearer prefix:

curl -X GET "https://api.identitycall.com/api/v1/public/recordings" \
  -H "Authorization: Bearer idc_your_api_key_here"

import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
headers = {
    "Authorization": f"Bearer {API_KEY}"
}
 
response = requests.get(
    "https://api.identitycall.com/api/v1/public/recordings",
    headers=headers
)

const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.com/api/v1/public/recordings',
  {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  }
);

<?php
$apiKey = getenv('IDENTITYCALL_API_KEY');
 
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.identitycall.com/api/v1/public/recordings",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey"
    ]
]);
$response = curl_exec($ch);

require 'net/http'
 
API_KEY = ENV['IDENTITYCALL_API_KEY']
 
uri = URI('https://api.identitycall.com/api/v1/public/recordings')
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{API_KEY}"
 
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

Permissions

API keys have three permission levels that control what operations they can perform:

Permission Combinations

Choose permissions based on your use case:

Error Responses

If you lack the required permission:

{
  "error": "Read permission required"
}

Status code: 403 Forbidden

Project Scoping

API keys can be scoped to a specific project:

• Account-wide: Key can access recordings from all projects in your account
• Project-scoped: Key can only access recordings from one specific project

Security Best Practices

Store Keys Securely

Never hardcode API keys in your source code. Use environment variables or a secrets manager:

# .env file (not committed to git)
IDENTITYCALL_API_KEY=idc_your_api_key_here

Add .env to your .gitignore:

# .gitignore
.env
.env.local

Use Minimal Permissions

Follow the principle of least privilege:

• Only grant the permissions your application actually needs
• Use read-only keys for analytics and monitoring
• Use project-scoped keys in production

Rotate Keys Regularly

Regenerate API keys periodically to limit exposure from potential leaks:

1. Go to Settings → API Keys
2. Click Regenerate on the key you want to rotate
3. Update your application with the new key
4. The old key is immediately invalidated

Set Expiration Dates

For temporary integrations or contractors:

1. Set an expiration date when creating the key
2. The key will automatically become invalid after that date
3. You’ll receive a notification before expiration

Monitor Usage

Track API key usage to detect anomalies:

• Check the Usage tab in your dashboard
• Set up alerts for unusual patterns
• Review which endpoints are being accessed

Error Handling

Invalid or Missing Key

{
  "error": "Invalid or expired API key"
}

Status code: 401 Unauthorized

Causes:

• API key is missing from the request
• API key format is incorrect
• API key has been revoked
• API key has expired

Rate Limiting

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Status code: 429 Too Many Requests

Solution: Wait for the time specified in retry_after (seconds) before retrying.

Managing Keys

Revoking a Key

If a key is compromised:

1. Go to Settings → API Keys
2. Click Revoke on the compromised key
3. The key is immediately invalidated
4. Create a new key if needed

Viewing Key Usage

Each key tracks:

• Last used timestamp
• Total requests
• Requests by endpoint
• Error rates

Access this in Settings → API Keys → View Usage.

Next Steps