Manage API Keys

API keys enable external systems to interact with the platform programmatically. This guide covers creating, using, monitoring, and revoking API keys.

Danger

API keys provide programmatic access. Keep them secure and never share publicly. Treat them like passwords.

---

Creating API Keys

1. Navigate to Settings → API Keys in the admin dashboard
2. Click Create New Key
3. Enter a descriptive name for the key (e.g., “CRM Integration”, “Mobile App”)
4. Select a role: Agent, Broker, or Admin
5. Assign to a brokerage (required for broker/agent keys)
6. Click Create
7. Copy the generated key immediately
8. Store it securely (password manager, encrypted vault)

Caution

The full key is only shown once at creation. If you lose it, you’ll need to generate a new key and update all integrations.

Key Naming Best Practices

Choose names that identify:

• What system uses it: “Zapier Integration”, “Mobile App”
• Who requested it: “John’s CRM Access”
• When it was created: “Production API - Jan 2024”

Good examples:

• “CRM Integration - Production”
• “Sarah’s Development Key”
• “Third-Party Analytics Service”

---

Using API Keys

Include your API key in the X-API-Key header with every request:

curl -H "X-API-Key: idx_your_key_here" \
     https://api.your-domain.com/api/properties

Integration Examples

JavaScript

const response = await fetch('https://api.your-domain.com/api/properties', {
  headers: {
    'X-API-Key': 'idx_your_key_here'
  }
});
const data = await response.json();

Python

import requests

headers = {'X-API-Key': 'idx_your_key_here'}
response = requests.get(
    'https://api.your-domain.com/api/properties',
    headers=headers
)
data = response.json()

cURL

curl -H "X-API-Key: idx_your_key_here" \
     https://api.your-domain.com/api/properties

Tip

For complete API documentation, see the API Reference. Key endpoints include Properties, Search, and Agents.

---

Monitoring API Usage

Track API activity in the admin dashboard to identify issues and optimize integrations.

Viewing Usage Metrics

Navigate to Settings → API Keys to see:

• Request counts — Total requests per key per time period
• Error rates — Percentage of 4xx and 5xx responses
• Response times — Average latency for successful requests
• Usage trends — Graphs showing request volume over time

Key Performance Indicators

Metric	What to Watch For
Request Count	Sudden spikes may indicate runaway scripts
Error Rate	>5% suggests integration problems
Response Time	>1s indicates performance issues
Last Used	Keys unused for 90+ days should be reviewed

Setting Up Alerts

1. Configure notification preferences in Settings → Notifications
2. Enable alerts for:
   • Rate limit exceeded
   • Unusual request patterns
   • High error rates
   • Suspicious activity

---

Handling Rate Limits

When your integration approaches or exceeds rate limits:

Check Rate Limit Status

Rate limit headers are included in every API response:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Implement Exponential Backoff

When you hit a rate limit (429 response):

1. Parse the Retry-After header
2. Wait the specified duration
3. Retry the request
4. If still failing, double the wait time
5. Maximum retry: 5 attempts

Example implementation:

async function makeRequest(url, attempt = 1) {
  const response = await fetch(url, {
    headers: { 'X-API-Key': apiKey }
  });

  if (response.status === 429 && attempt < 5) {
    const retryAfter = response.headers.get('Retry-After') || 60;
    await sleep(retryAfter * 1000);
    return makeRequest(url, attempt + 1);
  }

  return response;
}

Request a Limit Increase

If legitimate usage requires higher limits:

1. Contact your administrator
2. Provide justification (use case, expected volume)
3. Demonstrate current usage patterns
4. Limits can be adjusted per-key in admin settings

---

Revoking Keys

Disable keys that are compromised, unused, or no longer needed.

When to Revoke

• Employee/contractor leaves the organization
• Integration is decommissioned
• Key may have been exposed (committed to git, logged, etc.)
• Suspicious activity detected
• Routine security audit (rotate keys periodically)

Revocation Process

1. Navigate to Settings → API Keys
2. Find the key in the list
3. Click the Revoke button
4. Confirm the action
5. Update any active integrations using that key

Revoked keys stop working immediately. Any integrations using that key will receive 401 Unauthorized responses.

Caution

Revoking a key cannot be undone. You’ll need to create a new key if you revoke one accidentally.

---

Key Rotation

Regularly rotating API keys improves security.

Rotation Schedule

• Critical systems: Every 90 days
• Development keys: Every 180 days
• Low-risk integrations: Annually
• Immediately: On suspected compromise

Rotation Workflow

1. Create a new API key with the same permissions
2. Update integration to use the new key
3. Test that the integration works with the new key
4. Monitor for any issues (24-48 hours)
5. Revoke the old key
6. Document the rotation in your security log

---

Security Best Practices

Do’s

1. Use minimum required role — Don’t use admin keys for read-only operations
2. Rotate keys regularly — Especially after team changes
3. Monitor for anomalies — Review usage logs weekly
4. Use HTTPS only — Never send credentials over unencrypted connections
5. Store securely — Use environment variables or secret management services

Don’ts

1. Never expose keys in client-side code — Use server-side proxies instead
2. Don’t commit keys to version control — Add to .gitignore
3. Don’t share keys between services — Create separate keys for each integration
4. Don’t log API keys — Redact them in application logs
5. Don’t email or message keys — Use secure sharing methods

If a Key is Compromised

1. Immediately revoke the compromised key
2. Review recent activity for the key in usage logs
3. Create a new key with the same permissions
4. Update integrations to use the new key
5. Investigate how the compromise occurred
6. Document the incident for security audit

---

Related Documentation

• API Key Reference — Key format, permissions, and rate limits
• API Key Security — Security model and risk assessment
• API Overview — Complete API documentation